72 lines
2.3 KiB
Markdown
72 lines
2.3 KiB
Markdown
# Localization
|
|
|
|
The web interface uses JSON language packs from `lang/`. Language files are discovered at Rust build time and embedded in the application binary.
|
|
|
|
English (`lang/en.json`) is required and is always the fallback language. Polish (`lang/pl.json`) is included by default.
|
|
|
|
## Add a language
|
|
|
|
1. Copy `lang/en.json` to a file named with the new language code, for example `lang/de.json`.
|
|
2. Update the `meta` object.
|
|
3. Translate values inside `translations`. Do not rename translation keys.
|
|
4. Run `./scripts/dev.sh --check` or build the project again.
|
|
5. Start the rebuilt binary. The new language appears automatically in the language selector.
|
|
|
|
Example structure:
|
|
|
|
```json
|
|
{
|
|
"meta": {
|
|
"code": "de",
|
|
"name": "German",
|
|
"native_name": "Deutsch",
|
|
"locale": "de-DE"
|
|
},
|
|
"translations": {
|
|
"controls.language": "Sprache",
|
|
"controls.theme": "Darstellung"
|
|
}
|
|
}
|
|
```
|
|
|
|
The filename and `meta.code` must match (`de.json` -> `"code": "de"`). File names may contain ASCII letters, digits, `-` and `_` only.
|
|
|
|
## Fallback behavior
|
|
|
|
A language pack does not have to duplicate every English key while it is being developed. If a key is missing from the selected language, the UI uses the value from `en.json`. If a key is also missing from English, the translation key itself is shown, which makes incomplete strings visible during development.
|
|
|
|
## Build-time validation
|
|
|
|
`build.rs` checks that:
|
|
|
|
- at least one JSON language file exists,
|
|
- `en.json` exists,
|
|
- every language file contains valid JSON,
|
|
- every file has `meta.code`, `meta.name`, `meta.native_name` and `meta.locale`,
|
|
- `meta.code` matches the filename,
|
|
- `translations` is a JSON object.
|
|
|
|
A malformed language pack fails the Rust build instead of producing a broken selector at runtime.
|
|
|
|
## Runtime endpoints
|
|
|
|
The embedded language catalog is available at:
|
|
|
|
```text
|
|
GET /lang/index.json
|
|
```
|
|
|
|
Individual embedded packs are available at:
|
|
|
|
```text
|
|
GET /lang/en.json
|
|
GET /lang/pl.json
|
|
GET /lang/<code>.json
|
|
```
|
|
|
|
These endpoints are intentionally public so that localization also works before API authentication is completed.
|
|
|
|
## Browser preference
|
|
|
|
The selected language code is stored for one year in the `gree_controller_language` cookie. If the stored language is no longer present in a later build, the UI falls back to English.
|