i18n and locales (6 languages)

Read before editing translations, localized pages or content collections.

Languages and URLs

• 6 locales: en (default), fr, es, de, it, pt-br. Preserve locale keys exactly, including pt-br (never pt).
• URL pattern /{lang}/{path} (/fr/download, /es/blog/<slug>); root / redirects to /en.
• Locale folders must stay aligned across src/content/blog/<locale>/, src/content/help/<locale>/, src/pages/<locale>/rss.xml.ts and src/i18n/translations/<locale>.ts so navigation, hreflang and sitemap generation stay consistent.

Key files

• src/i18n/config.ts — languages object and validation (isValidLang()).
• src/i18n/utils.ts — t(lang, 'key.path') (dot notation for nested keys), getLocalizedUrl(lang, path), getLangFromUrl(url), getAlternateUrls(path), translationMap.
• src/i18n/translations/{lang}.ts — all UI strings and static content; nested keys such as changelog_content.v1_2_10.new_features.
• src/i18n/glossary.ts + scripts/i18n/glossary.json — terminology; npm run check:i18n:terminology (prebuild + CI) fails on banned tokens in scoped keys.
• src/content.config.ts — content collections schema (blog + help); its lang enum lists the 6 locales.

Pages

Every src/pages/[lang]/** page must export getStaticPaths() with all active languages, validate lang with isValidLang() and redirect to /en if invalid, and pass lang to BaseLayout and to every component. Components receive the lang prop and use t(lang, 'key').

Translations must be complete

• Every key exists in all 6 translations/{lang}.ts files (npm run test:i18n checks the rendered site).
• /add-i18n-section (.claude/commands/add-i18n-section.md) adds a new section to the 6 files in one pass.

Translation workflow: multilingual-translator agent (mandatory)

For any content translated into several languages (changelog entries, UI strings, static pages, marketing copy, legal text, blog posts) invoke .claude/agents/multilingual-translator.md (Task tool, subagent_type=multilingual-translator). It translates the 6 languages in parallel, keeps terminology consistent and preserves placeholders, formatting and markup. Do not translate sequentially by hand, do not copy-paste translation files without agent validation, do not use general-purpose agents for translation.

Content collections

• Blog: src/content/blog/{lang}/. Required frontmatter: title, description, date, lang; optional: tags, author, image, imageAlt, draft.
• Blog slugs are localized per language (never an English slug in a translation); production rules in .claude/rules/seo-content.md.
• Help: src/content/help/{lang}/, rendered by src/pages/[lang]/help/ and indexed by Pagefind at build time.

Adding a language

Follow docs/guides/adding-new-language.md: languages in config.ts → new translations/{lang}.ts → translationMap in utils.ts → lang enum in src/content.config.ts → getStaticPaths() of every [lang] page → src/content/blog/{lang}/ and help/{lang}/ → src/pages/{lang}/rss.xml.ts.

Reference

• docs/i18n/i18n-strategy.md — i18n strategy (Astro native features).
• docs/i18n/glossary_guide.md — glossary and terminology rules.