# Contributing Translations

Translation is handled by the [next-intl](https://next-intl-docs.vercel.app/) library. 

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.  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 (
        <>
            <h1>{t('home-hero-text')}</h1>
            <p>{t('home-hero-subtext')}</p>
        </>
    )
}
```

## 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:
```
<button>Click Me</button>
```

Translated:
```
<button>{t('translated-click-me')}
```

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).