Skip to content

Commit 76b1fa3

Browse files
authored
chore: update i18n contributing guide (#1030)
1 parent a729534 commit 76b1fa3

File tree

1 file changed

+40
-2
lines changed

1 file changed

+40
-2
lines changed

CONTRIBUTING.md

Lines changed: 40 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -340,12 +340,12 @@ To add a new locale:
340340
5. If the language is `right-to-left`, add `dir: 'rtl'` (see `ar-EG` in config for example)
341341
6. If the language requires special pluralization rules, add a `pluralRule` callback (see `ar-EG` or `ru-RU` in config for examples)
342342

343-
Check [Pluralization rule callback](https://vue-i18n.intlify.dev/guide/essentials/pluralization.html#custom-pluralization) for more info.
343+
Check [Pluralization rule callback](https://vue-i18n.intlify.dev/guide/essentials/pluralization#custom-pluralization) and [Plural Rules](https://cldr.unicode.org/index/cldr-spec/plural-rules#TOC-Determining-Plural-Categories) for more info.
344344

345345
### Update translation
346346

347347
We track the current progress of translations with [Lunaria](https://lunaria.dev/) on this site: https://i18n.npmx.dev/
348-
If you see any outdated translations in your language, feel free to update the keys to match then English version.
348+
If you see any outdated translations in your language, feel free to update the keys to match the English version.
349349

350350
In order to make sure you have everything up-to-date, you can run:
351351

@@ -408,13 +408,51 @@ See how `es`, `es-ES`, and `es-419` are configured in [config/i18n.ts](./config/
408408
<p>{{ $t('greeting', { name: userName }) }}</p>
409409
```
410410

411+
4. Don't concatenate string messages in the Vue templates, some languages can have different word order. Use placeholders instead.
412+
413+
**Bad:**
414+
415+
```vue
416+
<p>{{ $t('hello') }} {{ userName }}</p>
417+
```
418+
419+
**Good:**
420+
421+
```vue
422+
<p>{{ $t('greeting', { name: userName }) }}</p>
423+
```
424+
425+
**Complex content:**
426+
427+
If you need to include HTML or components inside the translation, use [`i18n-t`](https://vue-i18n.intlify.dev/guide/advanced/component.html) component. This is especially useful when the order of elements might change between languages.
428+
429+
```json
430+
{
431+
"agreement": "I accept the {terms} and {privacy}.",
432+
"terms_link": "Terms of Service",
433+
"privacy_policy": "Privacy Policy"
434+
}
435+
```
436+
437+
```vue
438+
<i18n-t keypath="agreement" tag="p">
439+
<template #terms>
440+
<NuxtLink to="/terms">{{ $t('terms_link') }}</NuxtLink>
441+
</template>
442+
<template #privacy>
443+
<strong>{{ $t('privacy_policy') }}</strong>
444+
</template>
445+
</i18n-t>
446+
```
447+
411448
### Translation key conventions
412449

413450
- Use dot notation for hierarchy: `section.subsection.key`
414451
- Keep keys descriptive but concise
415452
- Group related keys together
416453
- Use `common.*` for shared strings (loading, retry, close, etc.)
417454
- Use component-specific prefixes: `package.card.*`, `settings.*`, `nav.*`
455+
- Do not use dashes (`-`) in translation keys; always use underscore (`_`): e.g., `privacy_policy` instead of `privacy-policy`
418456

419457
### Using i18n-ally (recommended)
420458

0 commit comments

Comments
 (0)