Skip to content

Latest commit

 

History

History
255 lines (163 loc) · 5.31 KB

LOCALIZATION.md

File metadata and controls

255 lines (163 loc) · 5.31 KB

🌍 Localization Guide

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.


🛠 Translation Management

📝 Updating Existing Translations

  1. Run the following command to extract all translatable strings from your source code:

    npm run i18n:extract

    This updates each language’s messages.po file with new or modified strings.

  2. Open the relevant messages.po file 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"
  3. Re-run the extract command to validate your translations and ensure files are properly updated:

    npm run i18n:extract

➕ Adding a New Translatable String

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:extract

This updates all messages.po files with the new string.


🔁 Translating Dynamic Content

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:extract

🔢 Handling Plurals

To 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"

📘 Plurals Guide


🧩 Handling Nested Components

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>"

📘 Nested Components Guide


🚀 Translations in CI/CD

✅ Note: Translations are compiled in the CI/CD pipeline via the custom post-install script.

It utilizes the following commands:

🧪 Compiling Translations for Testing

npm run i18n:compile

This generates messages.js for each language from .po files.

🏁 Compiling Translations for Production

npm run i18n:compile:strict

Fails the build if there are any missing translations. This ensures full coverage before release.


🌐 Managing Locales

➕ Adding a New Language

  1. Add your locale to lingui.config.js:

    export default defineConfig({
      locales: ['en', 'fi', '<lang>'], // Add your language code here
    });
  2. Run:

    npm run i18n:extract

    This creates a new folder and messages.po file under src/locales/<lang>.

  3. Update your language switcher in i18n.tsx to include the new locale.

  4. If you are using the i18n:sync-csv script, you may need to update the locales in the script as well.


➖ Removing a Language

  1. Remove the locale from lingui.config.js:

    locales: ['en', 'fi'], // Remove your locale
  2. Then:

    • Run npm run i18n:extract
    • Delete the src/locales/<lang> folder
    • Update i18n.tsx accordingly
    • If using the i18n:sync-csv script, remove the locale from the script as well.

📁 Exporting/Importing Translations via CSV

Use the i18n:sync-csv script to work with translators outside the codebase.


📦 Export Translations (PO ➡️ CSV)

  1. Run:

    npm run i18n:sync-csv
  2. Choose "Export translations (PO to CSV)"

  3. Select which locales to export

  • The script will output .csv files to .translations/untranslated/<locale>.csv

✍️ Handling Translations with Translators

  1. Upload to the Excel file provided for translation
    (Check project links for the shared document)

  2. Translators should update the msgstr[0] column with their translations


📥 Import Translations (CSV ➡️ PO)

  1. Export the updated Excel sheet to CSV

⚠️ Important: Excel may break special characters. Use Google Sheets to import and re-export if needed.

  1. Run:

    npm run i18n:sync-csv
  2. Choose "Import translations (CSV to PO)"

  3. Select the locales

  • Input will be read from .translations/translated/<locale>.csv
  • The relevant messages.po files will be updated

❓ FAQ & Resources