This guide walks you through managing translations in your project using LinguiJS, including how to update translations, add new strings, manage dynamic and pluralized text, and export/import .po files via CSV.
-
Run the following command to extract all translatable strings from your source code:
npm run i18n:extract
This updates each language’s
messages.pofile with new or modified strings. -
Open the relevant
messages.pofile in a text editor and add your translations. For example:#: src/app/(auth)/index.tsx:74 #: src/app/(auth)/signup.tsx:55 msgid "Create an account" msgstr "Luo tili"
-
Re-run the extract command to validate your translations and ensure files are properly updated:
npm run i18n:extract
To mark a static string as translatable in your code:
import { Trans } from '@lingui/react/macro';
<Trans>Create an account</Trans>;Then run:
npm run i18n:extractThis updates all messages.po files with the new string.
For dynamic values like props or alt attributes:
import { useLingui } from '@lingui/react/macro';
export default function ImageWithCaption() {
const { t } = useLingui();
return <img src="..." alt={t`Image caption`} />;
}If you're outside of a React component or can't use hooks:
import { t } from "@lingui/core/macro";
export function SearchInput({
placeholder = t`Search`,
...
}) {
...
}Then extract the translations:
npm run i18n:extractTo localize pluralized content:
import { plural } from '@lingui/core/macro';
const message = plural(numBooks, {
one: '# Book',
other: '# Books',
});- If
numBooks = 1→ "1 Book" - If
numBooks = 2→ "2 Books"
Use nested components within <Trans> blocks for rich formatting:
<Trans>
<Text style={{ fontSize: 20 }}>
<Text>Concert of </Text>
<Text style={{ color: 'green' }}>Green Day</Text>
<Text style={{ fontWeight: 'bold' }}> tonight!</Text>
</Text>
</Trans>Will be extracted as:
"<0><1>Concert of </1><2>Green Day</2><3> tonight!</3></0>"
✅ Note: Translations are compiled in the CI/CD pipeline via the custom post-install script.
It utilizes the following commands:
npm run i18n:compileThis generates messages.js for each language from .po files.
npm run i18n:compile:strictFails the build if there are any missing translations. This ensures full coverage before release.
-
Add your locale to
lingui.config.js:export default defineConfig({ locales: ['en', 'fi', '<lang>'], // Add your language code here });
-
Run:
npm run i18n:extract
This creates a new folder and
messages.pofile undersrc/locales/<lang>. -
Update your language switcher in
i18n.tsxto include the new locale. -
If you are using the
i18n:sync-csvscript, you may need to update the locales in the script as well.
-
Remove the locale from
lingui.config.js:locales: ['en', 'fi'], // Remove your locale
-
Then:
- Run
npm run i18n:extract - Delete the
src/locales/<lang>folder - Update
i18n.tsxaccordingly - If using the
i18n:sync-csvscript, remove the locale from the script as well.
- Run
Use the i18n:sync-csv script to work with translators outside the codebase.
-
Run:
npm run i18n:sync-csv
-
Choose "Export translations (PO to CSV)"
-
Select which locales to export
- The script will output
.csvfiles to.translations/untranslated/<locale>.csv
-
Upload to the Excel file provided for translation
(Check project links for the shared document) -
Translators should update the
msgstr[0]column with their translations
- Export the updated Excel sheet to CSV
⚠️ Important: Excel may break special characters. Use Google Sheets to import and re-export if needed.
-
Run:
npm run i18n:sync-csv
-
Choose "Import translations (CSV to PO)"
-
Select the locales
- Input will be read from
.translations/translated/<locale>.csv - The relevant
messages.pofiles will be updated