You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
### 1. Use translations in components via `useTranslation` hook
41
+
42
+
This is the most common way. Using `useTranslation` makes the component re-render when the language changes, so that the messages are always up-to-date.
43
+
44
+
```tsx
45
+
function SomeComponent() {
46
+
const t =useTranslation()
47
+
48
+
// plain text messages are just plain strings
49
+
t.pages.index.title
50
+
51
+
// other kinds of messages are converted to functions that return a string
52
+
t.pages.index.error({ error: '404' })
53
+
54
+
// a pluralized message generates an extra `count` key to determine the plural form
// functional interpolation keys are only available in the `.jsx` function
61
+
t.pages.index.docs.jsx({ link: (s) => <ahref="/docs">{s}</a> })
62
+
}
63
+
```
64
+
65
+
### 2. Use translations outside components via the `i18n` object.
66
+
67
+
The `i18n` object serves messages of the current language. It has the same structure as the return value of `useTranslation`.
68
+
69
+
Note that this won't make the component re-render when the language changes, so it's suitable for static messages or messages that don't need to be updated frequently.
70
+
71
+
```ts
72
+
function getMessages() {
73
+
return {
74
+
title: i18n.pages.index.title,
75
+
error: i18n.pages.index.error({ error: '404' }),
76
+
}
77
+
}
78
+
79
+
function SomeComponent() {
80
+
getMessages()
81
+
}
82
+
```
83
+
84
+
### 3. Use translations outside components via the `i18nDefer` object.
85
+
86
+
It differs from `i18n` in that all messages, including plain text ones, are converted to functions, so that we can call them later to get up-to-date messages for the current language.
87
+
88
+
```ts
89
+
const title =i18nDefer.pages.index.title
90
+
const error =i18nDefer.pages.index.error
91
+
92
+
function Component() {
93
+
title()
94
+
error({ error: '404' })
95
+
}
96
+
```
97
+
98
+
## Workflow
99
+
100
+
There is a special section in `translations.json` called `essentials`, which will be statically bundled into the app for displaying messages before the overall translations are loaded. Specifically, it's used to render the error state when the translations fail to load.
101
+
102
+
`scripts/generate-translations.ts` is a Vite plugin that will split `translations.json` into a `.ts` file for each language, and an `essentials.ts` containing the `essentials` section of every language. The reason to use `.ts` is that it's strongly typed, allowing us to use the type information to generate strictly typed interpolation functions, which is impossible with `.json`.
103
+
104
+
A bonus by using `.ts` is that TypeScript can now trace the messages' references, so we can use IDE's "Go to definition" to inspect the referenced messages, or use "Find all references" to find where a message is referenced in the codebase.
105
+
106
+
During development, the plugin watches `translations.json`. When this file is modified, the plugin will re-generate the split files to trigger a hot reload.
0 commit comments