forked from
npmx.dev/npmx.dev
[READ-ONLY]
a fast, modern browser for the npm registry
docs(i18n): clarify locale setup and lunaria file requirement (#443)
authored by
Daniel Roe
and committed by
GitHub
b26b3c22
e690e38b
+33
-18
+33
-18
CONTRIBUTING.md
+33
-18
CONTRIBUTING.md
···
256
256
- `locales` object will be used to link the supported locales (country and single one)
257
257
- `buildLocales` function will build the target locales
258
258
259
-
To register a new locale:
259
+
To add a new locale:
260
260
261
-
- for a single country, your JSON file should include the language and the country in the name (for example, `pl-PL.json`) and register the info at `locales` object
262
-
- for multiple country variants, you need to add the default language JSON file (for example for Spanish, `es.json`) and one of the country variants (for example for Spanish for Spain, `es-ES.json`); register the language at `countryLocaleVariants` object adding the country variants with the JSON country file and register the language at `locales` object using the language JSON file (check how we register `es`, `es-ES` and `es-419` in [config/i18n.ts](./config/i18n.ts))
261
+
1. Create a new JSON file in [`i18n/locales/`](./i18n/locales) with the locale code as the filename (e.g., `uk-UA.json`, `de-DE.json`)
262
+
2. Copy [`en.json`](./i18n/locales/en.json) and translate the strings
263
+
3. Add the locale to the `locales` array in [config/i18n.ts](./config/i18n.ts):
263
264
264
-
The country file should contain will contain only the translations that differ from the language JSON file, Vue I18n will merge the messages for us.
265
+
```typescript
266
+
{
267
+
code: 'uk-UA', // Must match the filename (without .json)
268
+
file: 'uk-UA.json',
269
+
name: 'Українська', // Native name of the language
270
+
},
271
+
```
265
272
266
-
To add a new locale:
273
+
4. Copy your translation file to `lunaria/files/` for translation tracking:
274
+
275
+
```bash
276
+
cp i18n/locales/uk-UA.json lunaria/files/uk-UA.json
277
+
```
267
278
268
-
1. Add a new file at [locales](./i18n/locales) folder with the language code as the filename.
269
-
2. Copy [en](./i18n/locales/en.json) and translate the strings
270
-
3. Add the language to the `locales` array in [config/i18n.ts](./config/i18n.ts), below `en` and `ar`:
271
-
- If your language has multiple country variants, add the generic one for language only (only if there are a lot of common entries, you can always add it as a new one)
272
-
- Add all country variants in [country variants object](./config/i18n.ts)
273
-
- Add all country variants files with empty `messages` object: `{}`
274
-
- Translate the strings in the generic language file
275
-
- Later, when anyone wants to add the corresponding translations for the country variant, just override any entry in the corresponding file: you can see an example with `es` variants.
276
-
- If the generic language already exists:
277
-
- If the translation doesn't differ from the generic language, then add the corresponding translations in the corresponding file
278
-
- If the translation differs from the generic language, then add the corresponding translations in the corresponding file and remove it from the country variants entry
279
-
4. If the language is `right-to-left`, add `dir` option with `rtl` value, for example, for [ar](./config/i18n.ts)
280
-
5. If the language requires special pluralization rules, add `pluralRule` callback option, for example, for [ar](./config/i18n.ts)
279
+
> [!IMPORTANT]
280
+
> This file must be committed. Lunaria uses git history to track translation progress, so the build will fail if this file is missing.
281
+
282
+
5. If the language is `right-to-left`, add `dir: 'rtl'` (see `ar-EG` in config for example)
283
+
6. If the language requires special pluralization rules, add a `pluralRule` callback (see `ar-EG` or `ru-RU` in config for examples)
281
284
282
285
Check [Pluralization rule callback](https://vue-i18n.intlify.dev/guide/essentials/pluralization.html#custom-pluralization) for more info.
286
+
287
+
#### Country variants (advanced)
288
+
289
+
Most languages only need a single locale file. Country variants are only needed when you want to support regional differences (e.g., `es-ES` for Spain vs `es-419` for Latin America).
290
+
291
+
If you need country variants:
292
+
293
+
1. Create a base language file (e.g., `es.json`) with all translations
294
+
2. Create country variant files (e.g., `es-ES.json`, `es-419.json`) with only the differing translations
295
+
3. Register the base language in `locales` and add variants to `countryLocaleVariants`
296
+
297
+
See how `es`, `es-ES`, and `es-419` are configured in [config/i18n.ts](./config/i18n.ts) for a complete example.
283
298
284
299
### Adding translations
285
300