diff --git a/messages/README-LANGUAGES.md b/messages/README-LANGUAGES.md index ec15c0b..a1e84d0 100644 --- a/messages/README-LANGUAGES.md +++ b/messages/README-LANGUAGES.md @@ -1,18 +1,121 @@ # Contributing Translations -To contribute to the translation of your language you must modify the json in `/messages` that is named corresponding to the ISO Language Code of your given language. +Translation is handled by the [next-intl](https://next-intl-docs.vercel.app/) library. -If you do not see a JSON for your language then add the language. +To contribute to the translation of your language you must modify the JSON in `/messages` that is named corresponding to the [ISO Language Code](https://www.w3schools.com/tags/ref_language_codes.asp) of your given language. + +When modifying the key-value pairs in the JSON files, ensure you only change the value and not the key. + +Syntax: `"key": "value",` + +If you do not see a JSON for your language then may add the language by following the instructions below. + +## Dev Environment +Ensure you have Node.js and Git installed + +1) Fork the project repository by clicking the 'Fork' button then 'Create Fork' + +2) Clone your fork of the repo using the web url (or any other methods) +``` bash copy +git clone https://github.com/YOUR-GITHUB-USERNAME/www.git +``` +3) Change your current directory to the project directory +``` bash copy +cd www +``` +4) Install the project dependancies using npm +``` bash copy +npm install +``` +5) Start the development server using npm +``` bash copy +npm run dev +``` +6) Open a browser and go to http://localhost:3000/ + +7) Test translations by changing your browsers default language setting ## Adding a language -1. To add a language you must add the language to the `const SUPPORTED_LANGUAGES = ['en', 'de'];` variable in the `./src/i18n.ts` file. -2. You must create a new `.json` file in the `./messages` directory -3. Copy the contents of the `en.json` file, make your way down the key-value pairs and change **only the values** to the translated equivalent. - - - - - +1. Add the language to the `const SUPPORTED_LANGUAGES = ['en', 'de'];` variable in the `./src/i18n.ts` file. +2. Create a new `.json` file in the `./messages` directory named after the [ISO Language Code](https://www.w3schools.com/tags/ref_language_codes.asp) of the language (all lower case so language code es-ES should be es-es.json). +3. Copy the contents of the `en.json` file, make your way down the key-value pairs changing **only the values** to the translated equivalent. + +## Usage + +The key-value pairs are organised into parent keys called **namespaces**. + +In the JSON define the namespaces and their key-value pairs: +```json +{ + "home-page": { + "home-hero-text": "Zen is the best way to browse the web.", + "home-hero-subtext": "Beautifully designed, privacy-focused, and packed with features. We care about your experience, not your data.", +``` + +... then reference these key-value pairs in the TSX instead of using static text: + +```jsx +import { useTranslations } from "next-intl"; + +function HomePage() { + const t = useTranslations('home-page'); + + return ( + <> +

{t('home-hero-text')}

+

{t('home-hero-subtext')}

+ + ) +} +``` + +## Troubleshooting + +### Missing Key In JSON + +Each language JSON should have the same set of keys as all the others. If a language is missing a key then you will see the name of the *key* in place of the value on the website. + +You will also be able to see errors on the console in the browser developer tools. +``` +❌ Error: MISSING_MESSAGE: Could not resolve `home-hero-text` in messages for locale `en`. +``` +This means that en.json is missing the 'home-hero-text' key. + +If this occurs then find the key that is missing and add it to the JSON. + +### Key Is Not Referenced In The TSX + +Translations only work if the developer chooses to use the translated value in place of the static value in their HTML. + +Not translated: +``` + +``` + +Translated: +``` + @@ -43,27 +52,27 @@ export function MobileNav() { href="/download" onOpenChange={setOpen} > - Download + {t('mobile-download-link')} - Theme Store + {t('mobile-theme-store-link')} - Release Notes + {t('mobile-release-notes-link')} - Donate {"<"}3 + {t('mobile-donate-link')} {"<"}3 - {components.map(({title, href, description}) => ( + {translatedComponents.map(({title, href, description}) => ( ({ + title: t(component.titleKey), + href: component.href, + description: t(component.descriptionKey), + })); + + console.log(translatedComponents); + return (
@@ -63,7 +71,7 @@ export function Navigation() { - {t('getting-started')} + {t('nav-getting-started')}
  • @@ -74,23 +82,22 @@ export function Navigation() { >
    - Zen Browser + {t('nav-gs-zen-heading')}

    - Firefox based browser with a focus on privacy and - customization. + {t('nav-gs-zen-text')}

    • - - Start using Zen Browser today with just a few clicks. + + {t('nav-gs-download-li-text')} - - Customize your browser with a variety of themes! + + {t('nav-gs-themes-li-text')} - - Stay up to date with the latest changes. + + {t('nav-gs-release-text')}
@@ -98,30 +105,30 @@ export function Navigation() { - {t('donate')} + {t('nav-donate')}
    - Support us on Patreon and get exclusive rewards and keep the project alive. + {t('nav-donate-patreon-li-text')} - Ko-fi is a way to support us with a one-time donation and help us keep the project alive. + {t('nav-donate-ko-fi-li-text')}
- {t('useful-links')} + {t('nav-useful-links')}
    - {components.map((component) => ( + {translatedComponents.map((component) => (