I18n

Translation & i18n skill

Fill in missing translations (msgstr "") in all web-next/src/locales/*/messages.po files and ensure every translation meets the quality standards below.

Adding translatable strings to components

Import from ~/lib/i18n/macro.ts. Always call useLingui() at the top of the component to get the translation helpers.

Simple text

import { useLingui } from "~/lib/i18n/macro.ts";

function MyComponent() {
  const { t } = useLingui();
  return <Button>{t`Save`}</Button>;
}

t works in JSX children, attributes, and any expression context:

<Button title={t`Reply`}>…</Button>
<TextFieldLabel>{t`Content`}</TextFieldLabel>
placeholder={t`Search a language…`}
aria-label={t`Language`}

Variable interpolation

Embed runtime values directly in the template literal:

const { t } = useLingui();
t`Failed to sign out: ${error.message}`
t`To follow ${displayName()}, enter your Fediverse handle.`

Translations with JSX elements (Trans component)

When a translation needs inline JSX (links, bold, components), use the <Trans> component from ~/components/Trans.tsx. Placeholder keys use SCREAMING_SNAKE_CASE:

import { Trans } from "~/components/Trans.tsx";
import { useLingui } from "~/lib/i18n/macro.ts";

function MyComponent() {
  const { t } = useLingui();
  return (
    <Trans
      message={t`Verified that this link is owned by ${"OWNER"} ${"RELATIVE_TIME"}`}
      values={{
        OWNER: () => <strong>{actor().name}</strong>,
        RELATIVE_TIME: () => <Timestamp value={verified()} />,
      }}
    />
  );
}

Pluralization

Use i18n._(msg…) combined with plural(). The # symbol is replaced with the count:

import { msg, plural, useLingui } from "~/lib/i18n/macro.ts";

function FollowerCount(props: { count: number }) {
  const { i18n } = useLingui();
  return (
    <span>
      {i18n._(
        msg`${
          plural(props.count, {
            one: "# follower",
            other: "# followers",
          })
        }`,
      )}
    </span>
  );
}

Accessing the current locale

Use i18n.locale for locale-aware formatting (e.g., Intl APIs):

const { i18n } = useLingui();
date.toLocaleString(i18n.locale, { dateStyle: "full" })

Extracting messages

Before translating, run the extraction command to ensure .po files are up to date with the latest source code:

cd web-next && pnpm extract

This runs the extract script from web-next/package.json (lingui extract), which scans web-next/src/ for translatable strings (t`...`, msg`...`, plural(...)) and updates all web-next/src/locales/*/messages.po files. New strings appear as entries with empty msgstr "".

Run this before starting translation work to pick up any newly added or changed strings.

Workflow

1. Run cd web-next && pnpm extract to update .po files.
2. For each locale, read the mandatory terminology in web-next/src/locales/{locale}/glossary.txt and review nearby existing entries in messages.po for product voice and context.
3. Fill every empty msgstr "" with a translation that follows all rules below.
4. After translating, review existing non-empty msgstr entries for rule violations and fix them too.

Glossary enforcement

• Always use the exact term from glossary.txt when the source text contains a glossary term.
• If you encounter a term that should be standardized but is not in the glossary, ask the user via AskUserQuestion whether to add it.
• If the user agrees, add the entry to every locale's glossary.txt in the format term → translation (one per line, sorted alphabetically).

Punctuation & typography

All languages

en-US

• Quotation marks: " " (curly double), ' ' (curly single)
• Standard English punctuation rules
• Use sentence case for buttons, links, labels, headings, tabs, menu items, placeholders, and other UI strings. Do not use title case unless the text is a proper noun, brand name, protocol name, acronym, or another term that is conventionally capitalized. For example, write Create note, Save draft, and Remote follow, not Create Note, Save Draft, or Remote Follow.

ja-JP

• Quotation marks: 「」(single), 『』(double/nested)
• Fullwidth punctuation: 。 、 ！ ？
• No space before/after punctuation

ko-KR

• Quotation marks: 「」(single), 『』(double/nested)
• Period: halfwidth . (not fullwidth 。 — this is Korean standard)
• Comma, exclamation, question: , ! ? (halfwidth, Korean standard)
• No space before punctuation

zh-CN

• Quotation marks: 「」(single), 『』(double/nested)
• Fullwidth punctuation: 。 、 ！ ？
• No space before/after punctuation

zh-TW

• Quotation marks: 「」(single), 『』(double/nested)
• Fullwidth punctuation: 。 、 ！ ？
• No space before/after punctuation

Formality & tone