Skip to content

Commit 7656b12

Browse files
committed
chore: update i18n contributing guide
1 parent 18bcb8a commit 7656b12

1 file changed

Lines changed: 35 additions & 1 deletion

File tree

CONTRIBUTING.md

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -340,7 +340,7 @@ 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.html#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

@@ -408,13 +408,47 @@ 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+
{ "agreement": "I accept the {terms} and {privacy}." }
431+
```
432+
433+
```vue
434+
<i18n-t keypath="agreement" tag="p">
435+
<template #terms>
436+
<NuxtLink to="/terms">{{ $t('terms_link') }}</NuxtLink>
437+
</template>
438+
<template #privacy>
439+
<strong>{{ $t('privacy_policy') }}</strong>
440+
</template>
441+
</i18n-t>
442+
```
443+
411444
### Translation key conventions
412445

413446
- Use dot notation for hierarchy: `section.subsection.key`
414447
- Keep keys descriptive but concise
415448
- Group related keys together
416449
- Use `common.*` for shared strings (loading, retry, close, etc.)
417450
- Use component-specific prefixes: `package.card.*`, `settings.*`, `nav.*`
451+
- Do not use dashes (`-`) in traslation keys; always use underscore (`_`): e.g., `private_policy` instead of `private-policy`
418452

419453
### Using i18n-ally (recommended)
420454

0 commit comments

Comments
 (0)