Merge branch 'master' into vivek310111/added-navigation

asyncapi · Feb 12, 2024 · 9b2398a · 9b2398a
2 parents bfc729c + b1eccad
commit 9b2398a
Show file tree

Hide file tree

Showing 3 changed files with 340 additions and 26 deletions.
diff --git a/ADDING_TRANSLATIONS.md b/ADDING_TRANSLATIONS.md
@@ -0,0 +1,314 @@
+# Adding Translations to AsyncAPI Website <!-- omit in toc -->
+
+We appreciate your valuable contributions to the AsyncAPI website, whether it's adding or improving existing translations.
+
+## Table of contents <!-- omit in toc -->
+- [Improving existing translations:](#improving-existing-translations)
+- [Adding translations to a partially localized page:](#adding-translations-to-a-partially-localized-page)
+- [Adding translations to a new page:](#adding-translations-to-a-new-page)
+- [Adding a new locale:](#adding-a-new-locale)
+
+## Improving existing translations
+
+To modify or improve existing translations, simply navigate to the `locales` folder and edit the appropriate `JSON` files for your preferred language.
+
+Here is an example directory structure for the `locales` folder. It contains sub-folders named after different languages, each of which contains `JSON` files with key-value pairs for translations.
+
+The file `common.json` contains common translation keys such as buttons and CTAs. The other JSON files are specific to certain pages on the website. For instance, `tools.json` includes translations for all the tools-related pages on the website.
+
+```
+📦locales
+ ┣ 📂de
+ ┃ ┣ 📜common.json
+ ┃ ┣ 📜landing-page.json
+ ┃ ┗ 📜tools.json
+ ┃ ┗ 📜....json
+ ┗ 📂en
+ ┃ ┣ 📜common.json
+ ┃ ┣ 📜landing-page.json
+ ┃ ┗ 📜tools.json
+ ┃ ┗ 📜....json
+```
+
+To modify a `Landing Page`'s heading:
+- Navigate to the `locales` folder.
+- Select a language, e.g. `de` (German) - go to the `de` folder.
+- Open `landing-page.json`.
+- Change the values according to your needs.
+- Create a pull request with the changes.
+
+## Adding translations to a partially localized page
+
+The text on any given page may not have a translation available in your language.
+
+Use the translation hook with the key specified in the `locales` folder.
+
+Suppose the Landing Page has a button that is still in English when the language is set to German:
+- Navigate to the file where the component is defined.
+- Import the `useTranslation` hook from `lib/i18n`.
+- Extract the translation function from the hook `const { t } = useTranslation();`.
+- Use it to pass the key of the required translation value. Make sure to add the required key to the `locales` folder according to the page's scope. In this example, we are adding translation for a button, since all translation keys related to buttons need to be specified in `common.json`.
+
+Example:
+
+`ICSFileButton.js`
+```diff
+...
++ import { useTranslation } from '../../lib/i18n';
+
+export default function ICSFButton({
+- text = 'Download ICS File',
++ text = 'icsFileBtn',
+  ...
+}) {
+
++  const { t } = useTranslation('common');
+
+  return (
+    <Button
+-     text={text}
++     text={t(text)}
+      ...
+    />
+  )
+}
+```
+
+`en/common.json`
+```diff
+{
++    "icsFileBtn": "Download ICS File",
+}
+```
+
+`de/common.json`
+```diff
+{
++    "icsFileBtn": "ICS-Datei herunterladen",
+}
+```
+
+Ensure consistent naming in all `locales/[lang]/[file].json` files, and add a translation for all the locales present in the `locales` folder.
+
+> **NOTE**: You may also need to fix the cypress tests after adding a new translation key.
+
+## Adding translations to a new page
+
+The process for adding translations to a page that is not yet available in any existing locale is different from adding translations to a specific part of the page that is partially translated.
+
+**1. Create new JSON Files**
+  - Navigate to the `locales` folder.
+  - Create new `JSON` files with the same name in each of the `locales` folder. You may not need to create new `JSON` files in case there already exists a file with the same scope as your page. For example, all pages under the `tools/*` use the translation keys defined in `locales/[lang]/tools.json`.
+  - Skip to `Step 3` in case you haven't created new `JSON` files.
+
+**2. Modify the i18n configuration**
+  - Navigate to the `next-i18next-static-site.config.js` file in the root of the project folder.
+  - Add the name of the newly added `JSON` file to the `namespaces` array.
+
+**3. Add the static site functions**
+  - Copy the page(s) that you want to be localized to the `pages/[lang]/` folder according to the appropriate directory structure.
+  - Add the following functions at the bottom of the file for `i18n` to work.
+    ```js
+    export async function getStaticPaths() {
+        const paths = getAllLanguageSlugs();
+        return {
+            paths,
+            fallback: false,
+        };
+    }
+
+    export async function getStaticProps({ params }) {
+        const language = getLanguage(params.lang);
+        return {
+            props: {
+                language,
+            },
+        };
+    }
+    ```
+
+  - Follow the [Adding Translations guide](#adding-translations) to start translating the components
+
+**4. Configure i18n routing**
+After adding a new internationalized page, test it to sure the page is being served on the website when someone visits it.
+  - Replace the `next/link` component with the `LinkComponent` from `components/link.js` in the files where the page's `href` is being referenced.
+  - Make sure to add the exact same `href` to the `lib/i18nPaths.js` in the respective locales which support that `href`.
+
+  For example, if you want to translate the `pages/newsletter/index.js` page, so that if someone visits `asyncapi.com/de/newsletter`, it shows the page in the `German` locale.
+
+  - Add new `JSON` files to the `locales/en` and `locales/de` folder.
+
+  `locales` folder directory structure
+  ```diff
+    locales
+     ┣ de
+     ┃ ┣ common.json
+     ┃ ┣ landing-page.json
+  +  ┃ ┣ newsletter.json
+     ┃ ┗ tools.json
+     ┗ en
+     ┃ ┣ common.json
+     ┃ ┣ landing-page.json
+  +  ┃ ┣ newsletter.json
+     ┃ ┗ tools.json
+    ```
+
+  - Modify the `i18n` config to include the `newsletter` namespace.
+
+  ```diff
+  module.exports = {
+      i18n: {
+          languages: ["en", "de"],
+          defaultLanguage: "en",
+  -       namespaces: ["landing-page", "common", "tools"],
+  +       namespaces: ["landing-page", "common", "tools", "newsletter"],
+          defaultNamespace: "landing-page",
+      },
+  };
+  ```
+
+  - Copy and add static site functions to the `newsletter/index.js` page.
+
+  `pages` folder directory structure
+  ```diff
+    [lang]
+  +  ┣ newsletter
+  +  ┃ ┗ index.js
+     ┣ tools
+     ┃ ┗ cli.js
+     ┗ index.js
+  ```
+
+  `newsletter/index.js`
+  ```diff
+  ...
+  + import {
+  +   getAllLanguageSlugs,
+  +   getLanguage,
+  +   useTranslation
+  + } from "../../lib/i18n";
+
+  export default function NewsletterIndexPage() {
+
+  +  const { t } = useTranslation('newsletter');
+
+    return (
+      ...
+    );
+  }
+
+  + export async function getStaticPaths() {
+  +   const paths = getAllLanguageSlugs();
+  +   return {
+  +     paths,
+  +    fallback: false,
+  +  };
+  + }
+  + 
+  + export async function getStaticProps({ params }) {
+  +   const language = getLanguage(params.lang);
+  +   return {
+  +     props: {
+  +      language,
+  +    },
+  +   };
+  + }
+  ```
+
+  - Add custom route `LinkComponent` wherever the `next/link` is used for routing to the `/newsletter` href.
+
+  `lib/i18nPaths.js`
+  ```diff
+  const i18nPaths = {
+      en: [
+          "/tools/cli"
+  +       "/newsletter"
+      ],
+      de: [
+          "/tools/cli"
+  +       "/newsletter"
+      ]
+  };
+
+  export default i18nPaths;
+  ```
+
+You are now done with adding the localization to the `newsletter` page.
+
+> **Note**: Make sure to fix the Cypress tests after using the `useTranslation()` hook inside any component that Cypress is testing.
+
+## Adding a new locale
+
+AsyncAPI welcomes people from all over the world.
+
+There exist a few locales like `en` (English) and `de` (German) which have available localizations present.
+
+If you want to add a new locale like `fr` to serve pages in the French locale on the AsyncAPI website, follow these steps.
+
+**1. Create new JSON Files**
+  - Navigate to the `locales` folder.
+  - Create a new folder with the name of the locale you want to introduce.
+  - Create new `JSON` files with the same name as present in each of the other `locales` folders.
+  - Copy the existing `JSON` files present in the `en` folder. Change the values of those translation keys according to the new localization.
+
+**2. Modify i18n configuration**
+  - Navigate to the `next-i18next-static-site.config.js` file in the root of the project folder.
+  - Add the name of the newly added `locale` to the `languages` array.
+
+**3. Configure i18n routing**
+After adding a new internationalized page, ensure it is being served on the website when someone visits.
+  - Make sure to add the same `href` to the `lib/i18nPaths.js` in the respective locales supporting that `href`.
+
+If you have added the 'fr' locale and translated the 'tools/cli' page, clicking 'Tools -> CLI' in the navigation menu will redirect the user to 'asyncapi.com/fr/tools/cli'.
+
+`locales` folder structure
+```diff
+  locales
+   ┣ de
+   ┃ ┣ common.json
+   ┃ ┣ landing-page.json
+   ┃ ┗ tools.json
+   ┣ en
+   ┃ ┣ common.json
+   ┃ ┣ landing-page.json
+   ┃ ┗ tools.json
++  ┗ fr
++  ┃ ┣ common.json
++  ┃ ┣ landing-page.json
++  ┃ ┗ tools.json
+```
+
+- Change the `next-i18next-static-site.config.js` config.
+
+`next-i18next-static-site.config.js`
+```diff
+module.exports = {
+    i18n: {
+-       languages: ["en", "de"],
++       languages: ["en", "de", "fr"],
+        defaultLanguage: "en",
+        namespaces: ["landing-page", "common", "tools"],
+        defaultNamespace: "landing-page",
+    },
+};
+```
+ - Add new locale routing.
+
+`lib/i18nPaths.js`
+```diff
+const i18nPaths = {
+    en: [
+        "/tools/cli"
+    ],
+    de: [
+        "/tools/cli"
+    ],
++   fr: [
++       "/tools/cli"
++   ]
+};
+
+export default i18nPaths;
+```
+
+You are now done with adding a new locale. Congrats 🚀
diff --git a/pages/docs/reference/specification/v3.0.0.md b/pages/docs/reference/specification/v3.0.0.md
@@ -1818,7 +1818,7 @@ The Schema Object allows the definition of input and output data types.
 These types can be objects, but also primitives and arrays. This object is a superset of the [JSON Schema Specification Draft 07](https://json-schema.org/). The empty schema (which allows any instance to validate) MAY be represented by the `boolean` value `true` and a schema which allows no instance to validate MAY be represented by the `boolean` value `false`.
 
 Further information about the properties can be found in [JSON Schema Core](https://tools.ietf.org/html/draft-handrews-json-schema-01) and [JSON Schema Validation](https://tools.ietf.org/html/draft-handrews-json-schema-validation-01).
-Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here.
+Unless stated otherwise, the property definitions follow the JSON Schema specification as referenced here. For other formats (e.g., Avro, RAML, etc) see [Multi Format Schema Object](#multiFormatSchemaObject).
 
 ##### Properties