Fix translations when locale is not EN and no strings are defined

.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:

.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:

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 !!}
 

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 !!}
 
 <aside>
-    <strong>{{ __("scribe::base_url") }}</strong>: <code>{!! $baseUrl !!}</code>
+    <strong>{{ u::trans("scribe::base_url") }}</strong>: <code>{!! $baseUrl !!}</code>
 </aside>
 
 {!! $introText !!}

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 ?: '') !!}
 
 <span id="example-requests-{!! $endpoint->endpointId() !!}">
-<blockquote>{{ __("scribe::example_request") }}:</blockquote>
+<blockquote>{{ u::trans("scribe::example_request") }}:</blockquote>
 
 @foreach($metadata['example_languages'] as $language)
 
@@ -27,7 +28,7 @@
 @if($endpoint->isGet() || $endpoint->hasResponses())
     @foreach($endpoint->responses as $response)
         <blockquote>
-            <p>{{ __("scribe::example_response") }} ({{ $response->fullDescription() }}):</p>
+            <p>{{ u::trans("scribe::example_response") }} ({{ $response->fullDescription() }}):</p>
         </blockquote>
         @if(count($response->headers))
         <details class="annotation">
@@ -39,9 +40,9 @@
 @endforeach </code></pre></details> @endif
         <pre>
 @if(is_string($response->content) && Str::startsWith($response->content, "<<binary>>"))
-<code>{!! __("scribe::example_response.binary") !!} - {{ htmlentities(str_replace("<<binary>>", "", $response->content)) }}</code>
+<code>{!! u::trans("scribe::example_response.binary") !!} - {{ htmlentities(str_replace("<<binary>>", "", $response->content)) }}</code>
 @elseif($response->status == 204)
-<code>{!! __("scribe::example_response.empty") !!}</code>
+<code>{!! u::trans("scribe::example_response.empty") !!}</code>
 @else
 @php($parsed = json_decode($response->content))
 {{-- If response is a JSON string, prettify it. Otherwise, just print it --}}
@@ -51,15 +52,15 @@
 @endif
 </span>
 <span id="execution-results-{{ $endpoint->endpointId() }}" hidden>
-    <blockquote>{{ __("scribe::try_it_out.received_response") }}<span
+    <blockquote>{{ u::trans("scribe::try_it_out.received_response") }}<span
                 id="execution-response-status-{{ $endpoint->endpointId() }}"></span>:
     </blockquote>
     <pre class="json"><code id="execution-response-content-{{ $endpoint->endpointId() }}"
-      data-empty-response-text="<{{ __("scribe::example_response.empty") }}>" style="max-height: 400px;"></code></pre>
+      data-empty-response-text="<{{ u::trans("scribe::example_response.empty") }}>" style="max-height: 400px;"></code></pre>
 </span>
 <span id="execution-error-{{ $endpoint->endpointId() }}" hidden>
-    <blockquote>{{ __("scribe::try_it_out.request_failed") }}:</blockquote>
-    <pre><code id="execution-error-message-{{ $endpoint->endpointId() }}">{{ "\n\n".__("scribe::try_it_out.error_help") }}</code></pre>
+    <blockquote>{{ u::trans("scribe::try_it_out.request_failed") }}:</blockquote>
+    <pre><code id="execution-error-message-{{ $endpoint->endpointId() }}">{{ "\n\n".u::trans("scribe::try_it_out.error_help") }}</code></pre>
 </span>
 <form id="form-{{ $endpoint->endpointId() }}" data-method="{{ $endpoint->httpMethods[0] }}"
       data-path="{{ $endpoint->uri }}"
@@ -69,24 +70,24 @@
       autocomplete="off"
       onsubmit="event.preventDefault(); executeTryOut('{{ $endpoint->endpointId() }}', this);">
     <h3>
-        {{ __("scribe::endpoint.request") }}&nbsp;&nbsp;&nbsp;
+        {{ u::trans("scribe::endpoint.request") }}&nbsp;&nbsp;&nbsp;
         @if($metadata['try_it_out']['enabled'] ?? false)
             <button type="button"
                     style="background-color: #8fbcd4; padding: 5px 10px; border-radius: 5px; border-width: thin;"
                     id="btn-tryout-{{ $endpoint->endpointId() }}"
-                    onclick="tryItOut('{{ $endpoint->endpointId() }}');">{{ __("scribe::try_it_out.open") }}
+                    onclick="tryItOut('{{ $endpoint->endpointId() }}');">{{ u::trans("scribe::try_it_out.open") }}
             </button>
             <button type="button"
                     style="background-color: #c97a7e; padding: 5px 10px; border-radius: 5px; border-width: thin;"
                     id="btn-canceltryout-{{ $endpoint->endpointId() }}"
-                    onclick="cancelTryOut('{{ $endpoint->endpointId() }}');" hidden>{{ __("scribe::try_it_out.cancel") }}
+                    onclick="cancelTryOut('{{ $endpoint->endpointId() }}');" hidden>{{ u::trans("scribe::try_it_out.cancel") }}
             </button>&nbsp;&nbsp;
             <button type="submit"
                     style="background-color: #6ac174; padding: 5px 10px; border-radius: 5px; border-width: thin;"
                     id="btn-executetryout-{{ $endpoint->endpointId() }}"
-                    data-initial-text="{{ __("scribe::try_it_out.send") }}"
-                    data-loading-text="{{ __("scribe::try_it_out.loading") }}"
-                    hidden>{{ __("scribe::try_it_out.send") }}
+                    data-initial-text="{{ u::trans("scribe::try_it_out.send") }}"
+                    data-loading-text="{{ u::trans("scribe::try_it_out.loading") }}"
+                    hidden>{{ u::trans("scribe::try_it_out.send") }}
             </button>
         @endif
     </h3>
@@ -97,7 +98,7 @@
         </p>
     @endforeach
     @if(count($endpoint->headers))
-        <h4 class="fancy-heading-panel"><b>{{ __("scribe::endpoint.headers") }}</b></h4>
+        <h4 class="fancy-heading-panel"><b>{{ u::trans("scribe::endpoint.headers") }}</b></h4>
         @foreach($endpoint->headers as $name => $example)
             <?php
                 $htmlOptions = [];
@@ -122,7 +123,7 @@
         @endforeach
     @endif
     @if(count($endpoint->urlParameters))
-        <h4 class="fancy-heading-panel"><b>{{ __("scribe::endpoint.url_parameters") }}</b></h4>
+        <h4 class="fancy-heading-panel"><b>{{ u::trans("scribe::endpoint.url_parameters") }}</b></h4>
         @foreach($endpoint->urlParameters as $attribute => $parameter)
             <div style="padding-left: 28px; clear: unset;">
                 @component('scribe::components.field-details', [
@@ -140,7 +141,7 @@
         @endforeach
     @endif
     @if(count($endpoint->queryParameters))
-        <h4 class="fancy-heading-panel"><b>{{ __("scribe::endpoint.query_parameters") }}</b></h4>
+        <h4 class="fancy-heading-panel"><b>{{ u::trans("scribe::endpoint.query_parameters") }}</b></h4>
         @foreach($endpoint->queryParameters as $attribute => $parameter)
                 <?php
                 $htmlOptions = [];
@@ -165,7 +166,7 @@
         @endforeach
     @endif
     @if(count($endpoint->nestedBodyParameters))
-        <h4 class="fancy-heading-panel"><b>{{ __("scribe::endpoint.body_parameters") }}</b></h4>
+        <h4 class="fancy-heading-panel"><b>{{ u::trans("scribe::endpoint.body_parameters") }}</b></h4>
         <x-scribe::nested-fields
                 :fields="$endpoint->nestedBodyParameters" :endpointId="$endpoint->endpointId()"
         />
@@ -173,8 +174,8 @@
 </form>
 
 @if(count($endpoint->responseFields))
-    <h3>{{ __("scribe::endpoint.response") }}</h3>
-    <h4 class="fancy-heading-panel"><b>{{ __("scribe::endpoint.response_fields") }}</b></h4>
+    <h3>{{ u::trans("scribe::endpoint.response") }}</h3>
+    <h4 class="fancy-heading-panel"><b>{{ u::trans("scribe::endpoint.response_fields") }}</b></h4>
     <x-scribe::nested-fields
             :fields="$endpoint->nestedResponseFields" :endpointId="$endpoint->endpointId()"
             :isInput="false"

resources/views/themes/default/sidebar.blade.php

@@ -1,3 +1,6 @@
+@php
+    use Knuckles\Scribe\Tools\Utils as u;
+@endphp
 <a href="#" id="nav-button">
     <span>
         MENU
@@ -19,7 +22,7 @@
     @endisset
 
     <div class="search">
-        <input type="text" class="search" id="input-search" placeholder="{{ __("scribe::search") }}">
+        <input type="text" class="search" id="input-search" placeholder="{{ u::trans("scribe::search") }}">
     </div>
 
     <div id="toc">
@@ -52,10 +55,10 @@
 
     <ul class="toc-footer" id="toc-footer">
         @if($metadata['postman_collection_url'])
-            <li style="padding-bottom: 5px;"><a href="{!! $metadata['postman_collection_url'] !!}">{!! __("scribe::links.postman") !!}</a></li>
+            <li style="padding-bottom: 5px;"><a href="{!! $metadata['postman_collection_url'] !!}">{!! u::trans("scribe::links.postman") !!}</a></li>
         @endif
         @if($metadata['openapi_spec_url'])
-            <li style="padding-bottom: 5px;"><a href="{!! $metadata['openapi_spec_url'] !!}">{!! __("scribe::links.openapi") !!}</a></li>
+            <li style="padding-bottom: 5px;"><a href="{!! $metadata['openapi_spec_url'] !!}">{!! u::trans("scribe::links.openapi") !!}</a></li>
         @endif
         <li><a href="http://github.com/knuckleswtf/scribe">Documentation powered by Scribe ✍</a></li>
     </ul>

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 @@
                     @if(count($endpoint->headers))
                         <div class="sl-stack sl-stack--vertical sl-stack--5 sl-flex sl-flex-col sl-items-stretch">
                             <h3 class="sl-text-2xl sl-leading-snug sl-font-prose">
-                                {{ __("scribe::endpoint.headers") }}
+                                {{ u::trans("scribe::endpoint.headers") }}
                             </h3>
                             <div class="sl-text-sm">
                                 @foreach($endpoint->headers as $header => $value)
@@ -70,7 +71,7 @@
 
                     @if(count($endpoint->urlParameters))
                         <div class="sl-stack sl-stack--vertical sl-stack--6 sl-flex sl-flex-col sl-items-stretch">
-                            <h3 class="sl-text-2xl sl-leading-snug sl-font-prose">{{ __("scribe::endpoint.url_parameters") }}</h3>
+                            <h3 class="sl-text-2xl sl-leading-snug sl-font-prose">{{ u::trans("scribe::endpoint.url_parameters") }}</h3>
 
                             <div class="sl-text-sm">
                                 @foreach($endpoint->urlParameters as $attribute => $parameter)
@@ -93,7 +94,7 @@
 
                     @if(count($endpoint->queryParameters))
                             <div class="sl-stack sl-stack--vertical sl-stack--6 sl-flex sl-flex-col sl-items-stretch">
-                                <h3 class="sl-text-2xl sl-leading-snug sl-font-prose">{{ __("scribe::endpoint.query_parameters") }}</h3>
+                                <h3 class="sl-text-2xl sl-leading-snug sl-font-prose">{{ u::trans("scribe::endpoint.query_parameters") }}</h3>
 
                                 <div class="sl-text-sm">
                                     @foreach($endpoint->queryParameters as $attribute => $parameter)
@@ -115,7 +116,7 @@
 
                     @if(count($endpoint->nestedBodyParameters))
                         <div class="sl-stack sl-stack--vertical sl-stack--6 sl-flex sl-flex-col sl-items-stretch">
-                            <h3 class="sl-text-2xl sl-leading-snug sl-font-prose">{{ __("scribe::endpoint.body_parameters") }}</h3>
+                            <h3 class="sl-text-2xl sl-leading-snug sl-font-prose">{{ u::trans("scribe::endpoint.body_parameters") }}</h3>
 
                                 <div class="sl-text-sm">
                                     @component('scribe::themes.elements.components.nested-fields', [
@@ -129,7 +130,7 @@
 
                     @if(count($endpoint->responseFields))
                             <div class="sl-stack sl-stack--vertical sl-stack--6 sl-flex sl-flex-col sl-items-stretch">
-                                <h3 class="sl-text-2xl sl-leading-snug sl-font-prose">{{ __("scribe::endpoint.response_fields") }}</h3>
+                                <h3 class="sl-text-2xl sl-leading-snug sl-font-prose">{{ u::trans("scribe::endpoint.response_fields") }}</h3>
 
                                 <div class="sl-text-sm">
                                     @component('scribe::themes.elements.components.nested-fields', [
@@ -157,7 +158,7 @@
                             <div class="sl-panel__titlebar sl-flex sl-items-center sl-relative focus:sl-z-10 sl-text-base sl-leading-none sl-pr-3 sl-pl-4 sl-bg-canvas-200 sl-text-body sl-border-input focus:sl-border-primary sl-select-none">
                                 <div class="sl-flex sl-flex-1 sl-items-center sl-h-lg">
                                     <div class="sl--ml-2">
-                                        {{ __("scribe::example_request") }}:
+                                        {{ u::trans("scribe::example_request") }}:
                                         <select class="example-request-lang-toggle sl-text-base"
                                                 aria-label="Request Sample Language"
                                                 onchange="switchExampleLanguage(event.target.value);">
@@ -187,7 +188,7 @@
                                 <div class="sl-flex sl-flex-1 sl-items-center sl-py-2">
                                     <div class="sl--ml-2">
                                         <div class="sl-h-sm sl-text-base sl-font-medium sl-px-1.5 sl-text-muted sl-rounded sl-border-transparent sl-border">
-                                            <div class="sl-mb-2 sl-inline-block">{{ __("scribe::example_response") }}:</div>
+                                            <div class="sl-mb-2 sl-inline-block">{{ u::trans("scribe::example_response") }}:</div>
                                             <div class="sl-mb-2 sl-inline-block">
                                                 <select
                                                         class="example-response-{{ $endpoint->endpointId() }}-toggle sl-text-base"
@@ -240,9 +241,9 @@
                                             </details>
                                         @endif
                                         @if(is_string($response->content) && Str::startsWith($response->content, "<<binary>>"))
-                                            <pre><code>[{{ __("scribe::example_response.binary") }}] - {{ htmlentities(str_replace("<<binary>>", "", $response->content)) }}</code></pre>
+                                            <pre><code>[{{ u::trans("scribe::example_response.binary") }}] - {{ htmlentities(str_replace("<<binary>>", "", $response->content)) }}</code></pre>
                                         @elseif($response->status == 204)
-                                            <pre><code>[{{ __("scribe::example_response.empty") }}]</code></pre>
+                                            <pre><code>[{{ u::trans("scribe::example_response.empty") }}]</code></pre>
                                         @else
                                             @php($parsed = json_decode($response->content))
                                             {{-- If response is a JSON string, prettify it. Otherwise, just print it --}}

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
 
 <div class="sl-inverted">
@@ -260,7 +261,7 @@
                     <button type="button" data-endpoint="{{ $endpoint->endpointId() }}"
                             class="tryItOut-btn sl-button sl-h-sm sl-text-base sl-font-medium sl-px-1.5 sl-bg-primary hover:sl-bg-primary-dark active:sl-bg-primary-darker disabled:sl-bg-canvas-100 sl-text-on-primary disabled:sl-text-body sl-rounded sl-border-transparent sl-border disabled:sl-opacity-70"
                     >
-                        {{ __("scribe::try_it_out.send") }}
+                        {{ u::trans("scribe::try_it_out.send") }}
                     </button>
                 </div>
             </div>
@@ -279,13 +280,13 @@
                                       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"></path>
                             </svg>
                         </div>
-                        {{ __("scribe::try_it_out.request_failed") }}
+                        {{ u::trans("scribe::try_it_out.request_failed") }}
                     </div>
                 </div>
                 <div class="sl-panel__content-wrapper sl-bg-canvas-100 children" role="region">
                     <div class="sl-panel__content sl-p-4">
                         <p class="sl-pb-2"><strong class="error-message"></strong></p>
-                        <p class="sl-pb-2">{{ __("scribe::try_it_out.error_help") }}</p>
+                        <p class="sl-pb-2">{{ u::trans("scribe::try_it_out.error_help") }}</p>
                     </div>
                 </div>
             </div>
@@ -304,14 +305,14 @@
                                           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"></path>
                                 </svg>
                             </div>
-                            {{ __("scribe::try_it_out.received_response") }}
+                            {{ u::trans("scribe::try_it_out.received_response") }}
                         </div>
                     </div>
                     <div class="sl-panel__content-wrapper sl-bg-canvas-100 children" role="region">
                         <div class="sl-panel__content sl-p-4">
                             <p class="sl-pb-2 response-status"></p>
                             <pre><code class="sl-pb-2 response-content language-json"
-                                       data-empty-response-text="<{{ __("scribe::example_response.empty") }}>"
+                                       data-empty-response-text="<{{ u::trans("scribe::example_response.empty") }}>"
                                        style="max-height: 300px;"></code></pre>
                         </div>
                     </div>

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 @@ class ApiDetails
         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', '');
         }
 

src/Tools/Utils.php

@@ -353,6 +353,26 @@ class Utils
         );
     }
 
+    /**
+     * 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

src/Writing/HtmlWriter.php

@@ -9,6 +9,7 @@ use Knuckles\Camel\Output\OutputEndpointData;
 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 @@ class HtmlWriter
 
         // 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[] = "<a href=\"{$this->assetPathPrefix}collection.json\">".__("scribe::links.postman")."</a>";
+            $links[] = "<a href=\"{$this->assetPathPrefix}collection.json\">".u::trans("scribe::links.postman")."</a>";
             $postmanCollectionUrl = "{$this->assetPathPrefix}collection.json";
         }
         if ($this->config->get('openapi.enabled', false)) {
-            $links[] = "<a href=\"{$this->assetPathPrefix}openapi.yaml\">".__("scribe::links.openapi")."</a>";
+            $links[] = "<a href=\"{$this->assetPathPrefix}openapi.yaml\">".u::trans("scribe::links.openapi")."</a>";
             $openApiSpecUrl = "{$this->assetPathPrefix}openapi.yaml";
         }