From 02b37104ce3f0d137edf9ed1aafde07dae4b6962 Mon Sep 17 00:00:00 2001 From: Waled Khatiz Date: Sat, 31 Aug 2024 00:27:53 +1000 Subject: [PATCH 1/5] feat: Translating only navbar as POC --- messages/README-LANGUAGES.md | 84 ++++++++++-- messages/de.json | 248 +++++++++++++++++++++++++++++++++- messages/en.json | 248 +++++++++++++++++++++++++++++++++- src/components/mobile-nav.tsx | 23 +++- src/components/navigation.tsx | 63 +++++---- 5 files changed, 615 insertions(+), 51 deletions(-) diff --git a/messages/README-LANGUAGES.md b/messages/README-LANGUAGES.md index ec15c0b..f01d457 100644 --- a/messages/README-LANGUAGES.md +++ b/messages/README-LANGUAGES.md @@ -1,18 +1,82 @@ # 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. ## 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. +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) => ( Date: Sun, 1 Sep 2024 04:04:44 +1000 Subject: [PATCH 2/5] docs: more details in the README-LANGUAGES.md --- messages/README-LANGUAGES.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/messages/README-LANGUAGES.md b/messages/README-LANGUAGES.md index f01d457..8e11526 100644 --- a/messages/README-LANGUAGES.md +++ b/messages/README-LANGUAGES.md @@ -13,7 +13,7 @@ If you do not see a JSON for your language then may add the language by followin ## Adding a language 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. +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 @@ -75,6 +75,20 @@ Translated: The JSON is organized by the file names in the `/components` directory. Find the `.tsx` file that generates the untranslated text and modify it to use the translated value. +## Wrong Language Code + +It is common to mix up the 'es' language code with the 'es-ES' language code, for example. + +To see the language code that is actually being sent to the server you can do as follows: +1) Set your browser settings to the language you are trying to translate. +2) Open your browser developer tools. +3) Go to the 'Network' tab. +4) Ensure the Network tab is recording traffic (it typically is already recording). +5) Refresh the website and you will see all the requests the browser made to the server. +6) Scroll up to the very first request that was sent when you refreshed and click on it. The details of that request should be displayed. +7) In the 'Headers' tab of the details scroll down to 'Request Headers'. +8) Under 'Request Headers' you will see the 'Accept-Language' header whose value will be the language code(s) being sent by your browser, each with a 'q' value to specify which language code is most preferred. + ### Documentation If the error persists consult the [next-intl documentation](https://next-intl-docs.vercel.app/docs/getting-started). From df359b2bbe5ed7f7179ab6d9601d73d4c1742c94 Mon Sep 17 00:00:00 2001 From: Waled Khatiz Date: Sun, 1 Sep 2024 04:25:27 +1000 Subject: [PATCH 3/5] docs: even more details in the README-LANGUAGES.md --- messages/README-LANGUAGES.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/messages/README-LANGUAGES.md b/messages/README-LANGUAGES.md index 8e11526..cf80fba 100644 --- a/messages/README-LANGUAGES.md +++ b/messages/README-LANGUAGES.md @@ -10,6 +10,31 @@ 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. Add the language to the `const SUPPORTED_LANGUAGES = ['en', 'de'];` variable in the `./src/i18n.ts` file. From 47b034b39de573f610a925f3cc8be585fb32aef4 Mon Sep 17 00:00:00 2001 From: Waled Khatiz Date: Sun, 1 Sep 2024 04:31:11 +1000 Subject: [PATCH 4/5] typo: Fixing README.md subheading formatting --- messages/README-LANGUAGES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/messages/README-LANGUAGES.md b/messages/README-LANGUAGES.md index cf80fba..1c60277 100644 --- a/messages/README-LANGUAGES.md +++ b/messages/README-LANGUAGES.md @@ -100,7 +100,7 @@ Translated: The JSON is organized by the file names in the `/components` directory. Find the `.tsx` file that generates the untranslated text and modify it to use the translated value. -## Wrong Language Code +### Wrong Language Code It is common to mix up the 'es' language code with the 'es-ES' language code, for example. From bdc3d5c9c4bf58e7cf95ca2c86685b2f806a6220 Mon Sep 17 00:00:00 2001 From: Waled Khatiz Date: Sun, 1 Sep 2024 04:40:42 +1000 Subject: [PATCH 5/5] typo: Fix README.md syntax block markdown --- messages/README-LANGUAGES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/messages/README-LANGUAGES.md b/messages/README-LANGUAGES.md index 1c60277..a1e84d0 100644 --- a/messages/README-LANGUAGES.md +++ b/messages/README-LANGUAGES.md @@ -30,7 +30,7 @@ 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