diff --git a/ADDING_TRANSLATIONS.md b/ADDING_TRANSLATIONS.md new file mode 100644 index 000000000000..e4a26f9fefb1 --- /dev/null +++ b/ADDING_TRANSLATIONS.md @@ -0,0 +1,314 @@ +# Adding Translations to AsyncAPI Website + +We appreciate your valuable contributions to the AsyncAPI website, whether it's adding or improving existing translations. + +## Table of contents +- [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 ( +