From 8d2be2c681f71ed31c6be5043d6b1a0761f0235e Mon Sep 17 00:00:00 2001 From: shalvah Date: Fri, 5 May 2023 21:50:53 +0200 Subject: [PATCH] Fix translations when locale is not EN and no strings are defined --- .github/workflows/lint.yml | 2 +- .github/workflows/run-tests.yml | 2 +- resources/views/markdown/auth.blade.php | 7 +++- resources/views/markdown/intro.blade.php | 7 +++- .../views/themes/default/endpoint.blade.php | 41 ++++++++++--------- .../views/themes/default/sidebar.blade.php | 9 ++-- .../views/themes/elements/endpoint.blade.php | 19 +++++---- .../themes/elements/try_it_out.blade.php | 13 +++--- src/Extracting/ApiDetails.php | 5 ++- src/Tools/Utils.php | 20 +++++++++ src/Writing/HtmlWriter.php | 5 ++- 11 files changed, 82 insertions(+), 48 deletions(-) diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 0e6c9614..fb700a61 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -16,7 +16,7 @@ jobs: name: Lint code (PHP ${{ matrix.php }}) steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Setup PHP ${{ matrix.php }} uses: shivammathur/setup-php@v2 with: diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml index 5ca0f7eb..6383cff8 100644 --- a/.github/workflows/run-tests.yml +++ b/.github/workflows/run-tests.yml @@ -23,7 +23,7 @@ jobs: name: Tests (PHP ${{ matrix.php }} - ${{ matrix.deps }}) steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Setup PHP ${{ matrix.php }} uses: shivammathur/setup-php@v2 with: diff --git a/resources/views/markdown/auth.blade.php b/resources/views/markdown/auth.blade.php index 3bc8d96e..f70adf94 100644 --- a/resources/views/markdown/auth.blade.php +++ b/resources/views/markdown/auth.blade.php @@ -1,7 +1,10 @@ -# {{ __("scribe::headers.auth") }} +@php + use Knuckles\Scribe\Tools\Utils as u; +@endphp +# {{ u::trans("scribe::headers.auth") }} @if(!$isAuthed) -{!! __("scribe::no_auth") !!} +{!! u::trans("scribe::no_auth") !!} @else {!! $authDescription !!} diff --git a/resources/views/markdown/intro.blade.php b/resources/views/markdown/intro.blade.php index febe2b99..985cf8a9 100644 --- a/resources/views/markdown/intro.blade.php +++ b/resources/views/markdown/intro.blade.php @@ -1,9 +1,12 @@ -# {{ __("scribe::headers.introduction") }} +@php + use Knuckles\Scribe\Tools\Utils as u; +@endphp +# {{ u::trans("scribe::headers.introduction") }} {!! $description !!} {!! $introText !!} diff --git a/resources/views/themes/default/endpoint.blade.php b/resources/views/themes/default/endpoint.blade.php index faff5037..84ad1493 100644 --- a/resources/views/themes/default/endpoint.blade.php +++ b/resources/views/themes/default/endpoint.blade.php @@ -1,4 +1,5 @@ @php + use Knuckles\Scribe\Tools\Utils as u; /** @var Knuckles\Camel\Output\OutputEndpointData $endpoint */ @endphp @@ -12,7 +13,7 @@ {!! Parsedown::instance()->text($endpoint->metadata->description ?: '') !!} -
{{ __("scribe::example_request") }}:
+
{{ u::trans("scribe::example_request") }}:
@foreach($metadata['example_languages'] as $language) @@ -27,7 +28,7 @@ @if($endpoint->isGet() || $endpoint->hasResponses()) @foreach($endpoint->responses as $response)
-

{{ __("scribe::example_response") }} ({{ $response->fullDescription() }}):

+

{{ u::trans("scribe::example_response") }} ({{ $response->fullDescription() }}):

@if(count($response->headers))
@@ -39,9 +40,9 @@ @endforeach
@endif 
 @if(is_string($response->content) && Str::startsWith($response->content, "<>"))
-{!! __("scribe::example_response.binary") !!} - {{ htmlentities(str_replace("<>", "", $response->content)) }}
+{!! u::trans("scribe::example_response.binary") !!} - {{ htmlentities(str_replace("<>", "", $response->content)) }}
 @elseif($response->status == 204)
-{!! __("scribe::example_response.empty") !!}
+{!! u::trans("scribe::example_response.empty") !!}
 @else
 @php($parsed = json_decode($response->content))
 {{-- If response is a JSON string, prettify it. Otherwise, just print it --}}
@@ -51,15 +52,15 @@
 @endif

- {{ __("scribe::endpoint.request") }}    + {{ u::trans("scribe::endpoint.request") }}    @if($metadata['try_it_out']['enabled'] ?? false)    @endif

@@ -97,7 +98,7 @@

@endforeach @if(count($endpoint->headers)) -

{{ __("scribe::endpoint.headers") }}

+

{{ u::trans("scribe::endpoint.headers") }}

@foreach($endpoint->headers as $name => $example) urlParameters)) -

{{ __("scribe::endpoint.url_parameters") }}

+

{{ u::trans("scribe::endpoint.url_parameters") }}

@foreach($endpoint->urlParameters as $attribute => $parameter)
@component('scribe::components.field-details', [ @@ -140,7 +141,7 @@ @endforeach @endif @if(count($endpoint->queryParameters)) -

{{ __("scribe::endpoint.query_parameters") }}

+

{{ u::trans("scribe::endpoint.query_parameters") }}

@foreach($endpoint->queryParameters as $attribute => $parameter) nestedBodyParameters)) -

{{ __("scribe::endpoint.body_parameters") }}

+

{{ u::trans("scribe::endpoint.body_parameters") }}

@@ -173,8 +174,8 @@ @if(count($endpoint->responseFields)) -

{{ __("scribe::endpoint.response") }}

-

{{ __("scribe::endpoint.response_fields") }}

+

{{ u::trans("scribe::endpoint.response") }}

+

{{ u::trans("scribe::endpoint.response_fields") }}

MENU @@ -19,7 +22,7 @@ @endisset
- +
@@ -52,10 +55,10 @@ diff --git a/resources/views/themes/elements/endpoint.blade.php b/resources/views/themes/elements/endpoint.blade.php index d3757cbd..b1baf6cb 100644 --- a/resources/views/themes/elements/endpoint.blade.php +++ b/resources/views/themes/elements/endpoint.blade.php @@ -1,4 +1,5 @@ @php + use Knuckles\Scribe\Tools\Utils as u; /** @var Knuckles\Camel\Output\OutputEndpointData $endpoint */ @endphp @@ -48,7 +49,7 @@ class="sl-overflow-x-hidden sl-truncate sl-text-muted">{{ rtrim($baseUrl, '/') } @if(count($endpoint->headers))

- {{ __("scribe::endpoint.headers") }} + {{ u::trans("scribe::endpoint.headers") }}

@foreach($endpoint->headers as $header => $value) @@ -70,7 +71,7 @@ class="sl-overflow-x-hidden sl-truncate sl-text-muted">{{ rtrim($baseUrl, '/') } @if(count($endpoint->urlParameters))
-

{{ __("scribe::endpoint.url_parameters") }}

+

{{ u::trans("scribe::endpoint.url_parameters") }}

@foreach($endpoint->urlParameters as $attribute => $parameter) @@ -93,7 +94,7 @@ class="sl-overflow-x-hidden sl-truncate sl-text-muted">{{ rtrim($baseUrl, '/') } @if(count($endpoint->queryParameters))
-

{{ __("scribe::endpoint.query_parameters") }}

+

{{ u::trans("scribe::endpoint.query_parameters") }}

@foreach($endpoint->queryParameters as $attribute => $parameter) @@ -115,7 +116,7 @@ class="sl-overflow-x-hidden sl-truncate sl-text-muted">{{ rtrim($baseUrl, '/') } @if(count($endpoint->nestedBodyParameters))
-

{{ __("scribe::endpoint.body_parameters") }}

+

{{ u::trans("scribe::endpoint.body_parameters") }}

@component('scribe::themes.elements.components.nested-fields', [ @@ -129,7 +130,7 @@ class="sl-overflow-x-hidden sl-truncate sl-text-muted">{{ rtrim($baseUrl, '/') } @if(count($endpoint->responseFields))
-

{{ __("scribe::endpoint.response_fields") }}

+

{{ u::trans("scribe::endpoint.response_fields") }}

@component('scribe::themes.elements.components.nested-fields', [ @@ -157,7 +158,7 @@ class="sl-overflow-x-hidden sl-truncate sl-text-muted">{{ rtrim($baseUrl, '/') }
- {{ __("scribe::example_request") }}: + {{ u::trans("scribe::example_request") }}: @endif @if(is_string($response->content) && Str::startsWith($response->content, "<>")) - 
[{{ __("scribe::example_response.binary") }}] - {{ htmlentities(str_replace("<>", "", $response->content)) }}
+ 
[{{ u::trans("scribe::example_response.binary") }}] - {{ htmlentities(str_replace("<>", "", $response->content)) }}
@elseif($response->status == 204) - 
[{{ __("scribe::example_response.empty") }}]
+ 
[{{ u::trans("scribe::example_response.empty") }}]
@else @php($parsed = json_decode($response->content)) {{-- If response is a JSON string, prettify it. Otherwise, just print it --}} diff --git a/resources/views/themes/elements/try_it_out.blade.php b/resources/views/themes/elements/try_it_out.blade.php index 6033c677..d1d5590d 100644 --- a/resources/views/themes/elements/try_it_out.blade.php +++ b/resources/views/themes/elements/try_it_out.blade.php @@ -1,5 +1,6 @@ @php -/** @var \Knuckles\Camel\Output\OutputEndpointData $endpoint */ + use Knuckles\Scribe\Tools\Utils as u; + /** @var \Knuckles\Camel\Output\OutputEndpointData $endpoint */ @endphp
@@ -260,7 +261,7 @@ class="sl-relative sl-w-full sl-h-md sl-text-base sl-pr-2.5 sl-pl-2.5 sl-rounded
@@ -279,13 +280,13 @@ class="svg-inline--fa fa-caret-down fa-fw sl-icon" role="img" d="M310.6 246.6l-127.1 128C176.4 380.9 168.2 384 160 384s-16.38-3.125-22.63-9.375l-127.1-128C.2244 237.5-2.516 223.7 2.438 211.8S19.07 192 32 192h255.1c12.94 0 24.62 7.781 29.58 19.75S319.8 237.5 310.6 246.6z">
- {{ __("scribe::try_it_out.request_failed") }} + {{ u::trans("scribe::try_it_out.request_failed") }}

-

{{ __("scribe::try_it_out.error_help") }}

+

{{ u::trans("scribe::try_it_out.error_help") }}

@@ -304,14 +305,14 @@ class="svg-inline--fa fa-caret-down fa-fw sl-icon" role="img" d="M310.6 246.6l-127.1 128C176.4 380.9 168.2 384 160 384s-16.38-3.125-22.63-9.375l-127.1-128C.2244 237.5-2.516 223.7 2.438 211.8S19.07 192 32 192h255.1c12.94 0 24.62 7.781 29.58 19.75S319.8 237.5 310.6 246.6z">
- {{ __("scribe::try_it_out.received_response") }} + {{ u::trans("scribe::try_it_out.received_response") }} 

"
+                                       data-empty-response-text="<{{ u::trans("scribe::example_response.empty") }}>"
                                        style="max-height: 300px;">
diff --git a/src/Extracting/ApiDetails.php b/src/Extracting/ApiDetails.php index 9c2995f3..febe4b9c 100644 --- a/src/Extracting/ApiDetails.php +++ b/src/Extracting/ApiDetails.php @@ -3,6 +3,7 @@ namespace Knuckles\Scribe\Extracting; use Knuckles\Scribe\Tools\ConsoleOutputUtils as c; +use Knuckles\Scribe\Tools\Utils as u; use Knuckles\Scribe\Tools\DocumentationConfig; /** @@ -90,11 +91,11 @@ public function writeAuthMarkdownFile(): void if ($isAuthed) { $strategy = $this->config->get('auth.in'); $parameterName = $this->config->get('auth.name'); - $authDescription = __("scribe::auth.instruction.$strategy", [ + $authDescription = u::trans("scribe::auth.instruction.$strategy", [ 'parameterName' => $parameterName, 'placeholder' => $this->config->get('auth.placeholder') ?: 'your-token'] ); - $authDescription .= "\n\n".__("scribe::auth.details"); + $authDescription .= "\n\n".u::trans("scribe::auth.details"); $extraInfo = $this->config->get('auth.extra_info', ''); } diff --git a/src/Tools/Utils.php b/src/Tools/Utils.php index 294ac9e7..5d183718 100644 --- a/src/Tools/Utils.php +++ b/src/Tools/Utils.php @@ -353,6 +353,26 @@ public static function filterDocBlockTags(array $tags, string ...$names): array ); } + /** + * Like Laravel's trans/__ function, but will fallback to using the default translation if translation fails. + * For instance, if the user's locale is DE, but they have no DE strings defined, + * Laravel simply renders the translation key. + * Instead, we render the EN version. + */ + public static function trans(string $key, array $replace = []) + { + $translation = trans($key, $replace); + + if ($translation === $key) { + $translation = trans($key, $replace, config('app.fallback_locale')); + } + + if ($translation === $key) { + return trans($key, $replace, 'en'); + } + + return $translation; + } } function getTopLevelItemsFromMixedOrderList(array $mixedList): array diff --git a/src/Writing/HtmlWriter.php b/src/Writing/HtmlWriter.php index d1f52160..b40b8522 100644 --- a/src/Writing/HtmlWriter.php +++ b/src/Writing/HtmlWriter.php @@ -9,6 +9,7 @@ use Knuckles\Scribe\Tools\DocumentationConfig; use Knuckles\Scribe\Tools\MarkdownParser; use Knuckles\Scribe\Tools\Utils; +use Knuckles\Scribe\Tools\Utils as u; use Knuckles\Scribe\Tools\WritingUtils; /** @@ -112,11 +113,11 @@ public function getMetadata(): array // NB:These paths are wrong for laravel type but will be set correctly by the Writer class if ($this->config->get('postman.enabled', true)) { - $links[] = "assetPathPrefix}collection.json\">".__("scribe::links.postman").""; + $links[] = "assetPathPrefix}collection.json\">".u::trans("scribe::links.postman").""; $postmanCollectionUrl = "{$this->assetPathPrefix}collection.json"; } if ($this->config->get('openapi.enabled', false)) { - $links[] = "assetPathPrefix}openapi.yaml\">".__("scribe::links.openapi").""; + $links[] = "assetPathPrefix}openapi.yaml\">".u::trans("scribe::links.openapi").""; $openApiSpecUrl = "{$this->assetPathPrefix}openapi.yaml"; }