Localization

The Inject Exercise Platform (IXP) supports multiple languages through its localization features. This allows users to interact with the platform in their preferred language, enhancing accessibility and user experience. The localization system is built using the i18next library, which provides a robust framework for managing translations and internationalization (i18n) in web applications.

The language can be set by the user in the user settings. Note that only the frontend is localized, so the language setting does not affect any errors returned by the backend. Additionally, the language of an exercise depends on the content created in the exercise definition, so it may not always match the user's selected language.

Note

Localization is currently supported for the whole trainee and instructor views. The analyst view and the editor are not localized.

Adding a New Language

The localization is handled entirely on the frontend in a dedicated locale package. To add a new language to the IXP, you need to follow these steps:

Clone the Frontend Repository: If you haven't already, clone the frontend repository to your local machine using Git:
```
git clone https://gitlab.fi.muni.cz/inject/frontend.git
```
Create a New Directory: In the frontend repository, in the locale/resources/ directory, create a new folder named after the language code (e.g., fr for French).
Add Translation Files: Inside the new language folder, create a JSON file called core.json. Populate this file with key-value pairs for the translations.

Update i18n Configuration: In the locale/i18n.ts file, import the new translation resource and add it to the RESOURCES object. This will make the new language available in the application. For example, if you added French, you would import the resources and add them like this:

import csCoreResources from './resources/cs/core.json'
import enCoreResources from './resources/en/core.json'
import ptCoreResources from './resources/pt/core.json'
import frCoreResources from './resources/fr/core.json'

export const RESOURCES = {
en: {
    core: enCoreResources,
},
cs: {
    core: csCoreResources,
},
pt: {
    core: ptCoreResources,
},
fr: {
    core: frCoreResources,
},
} as const

Validate Translations: Ensure that all translation keys are properly defined and that there are no missing or duplicate keys. You can use the prepared script by running this command:
```
yarn # Install dependencies
yarn validate-translations # Run the validation script
```
Send us the Translations: Stage all your changes and create a git patch file containing all your changes:
```
git add .
git diff --cached > new-language.patch
```
Send the patch file to us to our address. We'll review your changes and apply them to the repository.

Alternatively, you can contact us directly to discuss the best way to contribute your translations.

Warning

The resources for each language are not automatically generated or updated. When new keys are added to the frontend, they need to be manually added to each language's translation files. Therefore, we cannot guarantee that all languages are always fully up to date with the latest frontend changes. This may lead to some missing translations, which will fall back to the default language (English) in the application.

Update Existing Translations after Frontend Changes

When the frontend is updated, new translation keys may be added, and existing keys may be modified or removed. To keep the translations up to date, follow these steps:

Pull the Latest Changes: Ensure you have the latest version of the frontend repository by pulling the latest changes from the remote repository.
```
git pull origin main
```
Check for New or Modified Keys: Review the changes in the frontend codebase to identify any new or modified translation keys. You can use the prepared script to check for missing translations:
```
yarn # Install dependencies
yarn validate-translations # Run the validation script
```
Update Translation Files: For each language you maintain, update the corresponding translation files in the locale/resources/ directory. Add new keys and modify existing ones as needed.
Validate Translations: After updating the translation files, run the validation script again to ensure that there are no missing or duplicate keys.
Send us the Updated Translations: Send us a git patch containing the updated translation files, following the same process as when adding a new language. We'll review your changes and apply them to the repository.