Merge pull request #212 from Authress-Engineering/enable-locale-speci…

…fication

Allow specifying the locale of the spec. fix #207

CHANGELOG.md

@@ -7,6 +7,7 @@ This package follows standard semvar, `<major>.<minor>.<build>`. No breaking cha
 * `fill-defaults` has now be inverted to be `hide-defaults` this brings it in line with how html boolean attributes are supposed to work. If you set this value to false previously, now you can hide the section using the new property.
 * `enable-console` has now be inverted to be `hide-console` this brings it in line with how html boolean attributes are supposed to work. If you set this value to false previously, now you can hide the section using the new property.
 * Fix `constraints` display for query parameters.
+* Add `x-locale` vendor extension to specify the locale of the spec.
 
 ## 1.1 ##
 * Support dynamic curl creation.

docs/documentation.md

@@ -202,29 +202,14 @@ requestInterceptor(event) {
 ```
 
 
-### SDK code samples
-OpenAPI Explorer supports inline code samples using the `x-code-samples` OpenAPI vendor extension. Just add your code sample into the array and it will dynamically appear as an example in the doc.
-```json
-"get": {
-  "x-code-samples": [{
-    "lang": "Javascript",
-    "label": "JS + Axios",
-    "source": "console.log('This is a code sample')"
-  }]
-}
-```
-<p>
-  <img src="./code-samples.png" alt="Code Samples" width="600px">
-</p>
-
-### Determining where the user is
+## Determining where the user is
 Knowing exactly where the user is can be tricky. One way is add the event listener for the type `event`. Another way is to search for the open slot dedicated to the current path details. The `path-details` slot is dynamically rendered with the appropriate `method` and `path` data properties. You can pull these out by doing this:
 ```js
 document.getElementsByTagName("openapi-explorer")[0].shadowRoot.querySelectorAll('slot[name=path-details]')[0].attributes['data-method'].value;
 document.getElementsByTagName("openapi-explorer")[0].shadowRoot.querySelectorAll('slot[name=path-details]')[0].attributes['data-path'].value;
 ```
 
-### Styling using CSS variables
+## Styling using CSS variables
 In many cases these might have already been set by your css framework, if not, and you want to override the the defaults to match your theme. For more in-depth options check out [How to style your openapi-explorer UI](./styling.md).
 * CSS (default set to page fonts) - Add to your css
 ```css
@@ -240,4 +225,37 @@ openapi-explorer {
   --pink: #e83e8c;
   --white: #fff;
 }
-```
+```
+
+## Vendor Overlays and custom properties
+The spec includes the ability to specify additional custom properties directly into the spec:
+
+### `x-locale` - Spec language & locale
+The specification itself can have its locale set so that the OpenAPI Explorer can automatically render in the correct language. Set the `x-locale` option into the `info` property, and if the OpenApi Specification has been translated into that language it will be converted.
+```json
+{
+    "openapi": "3.1.0",
+    "info": {
+        "title": "Test API",
+        "version": "1.0.0",
+        "x-locale": "en-US"
+    }
+}
+```
+
+For additional translated languages, please file a PR which includes translations for the keys defined in the [English Translation](../src/languages/en.js).
+
+### `x-code-samples` - SDK code samples
+OpenAPI Explorer supports inline code samples using the `x-code-samples` OpenAPI vendor extension. Just add your code sample into the array and it will dynamically appear as an example in the doc.
+```json
+"get": {
+  "x-code-samples": [{
+    "lang": "Javascript",
+    "label": "JS + Axios",
+    "source": "console.log('This is a code sample')"
+  }]
+}
+```
+<p>
+  <img src="./code-samples.png" alt="Code Samples" width="600px">
+</p>

src/languages/index.js

@@ -2,8 +2,8 @@ import i18next from 'i18next';
 import en from './en.js';
 import fr from './fr.js';
 
-export async function initI18n() {
-  const initLang = window.navigator.language.substring(0, 2);
+export async function initI18n(resolvedSpecLanguage) {
+  const initLang = (resolvedSpecLanguage || window.navigator.language).substring(0, 2);
   await i18next.init({
     lng: initLang,
     fallbackLng: 'en',

src/openapi-explorer.js

@@ -411,7 +411,6 @@ export default class OpenApiExplorer extends LitElement {
     this.handleResize = this.handleResize.bind(this);
     window.addEventListener('resize', this.handleResize);
     this.loading = true;
-    initI18n();
 
     const parent = this.parentElement;
     if (parent) {
@@ -563,6 +562,7 @@ export default class OpenApiExplorer extends LitElement {
         console.error('Unable to resolve the API spec. '); // eslint-disable-line no-console
         return;
       }
+      initI18n(spec.info?.['x-locale']);
       if (!this.serverUrl) {
         this.serverUrl = spec.servers[0]?.computedUrl || spec.servers[0]?.url;
       }