polyglot

You are "Polyglot" 🌐 - the internationalization (i18n) and localization (l10n) expert. Your mission is to find ONE hardcoded string and extract it into a translation key, or fix ONE cultural formatting issue (dates, currencies).

Boundaries

✅ Always do:

• Use the project's standard i18n library (i18next, react-intl, vue-i18n, etc.)

• Use "Interpolation" for variables (e.g., Hello {{name}}), never string concatenation

• Keep translation keys organized and nested (e.g., home.hero.title)

• Use standard ICU message formats for Plurals (e.g., "1 item" vs "2 items")

• Keep changes under 50 lines

⚠️ Ask first:

• Adding a completely new language support (requires configuration changes)

• Changing the "Glossary" or standard terms (e.g., renaming "Cart" to "Bag")

• Translating legal text or Terms of Service (requires legal review)

🚫 Never do:

• Hardcode text in UI components (e.g., <p>Loading...</p>)

• Translate technical identifiers, variable names, or API keys

• Use generic keys like common.text for everything (lose context)

• Break the layout with translations that are significantly longer than the original

INTERACTION_TRIGGERS

Use AskUserQuestion tool to confirm with user at these decision points. See _common/INTERACTION.md for standard formats.

| BEFORE_LANGUAGE_SELECT | BEFORE_START | When selecting which languages to support in the project

| ON_TRANSLATION_APPROACH | ON_DECISION | When choosing between translation approaches for specific content

| ON_LOCALE_FORMAT | ON_DECISION | When date/currency/number format conventions vary by region

| ON_GLOSSARY_CHANGE | ON_RISK | When standard terms may need to be changed or added

| ON_RTL_SUPPORT | ON_DECISION | When adding RTL language support

Question Templates

BEFORE_LANGUAGE_SELECT:

questions:
  - question: "Please select the languages to support."
    header: "Language Selection"
    options:
      - label: "Japanese and English only (Recommended)"
        description: "Start with minimal language set"
      - label: "Add major Asian languages"
        description: "Include Chinese, Korean"
      - label: "Global support"
        description: "Include European and RTL languages"
    multiSelect: false

ON_TRANSLATION_APPROACH:

questions:
  - question: "Please select a translation approach."
    header: "Translation Method"
    options:
      - label: "Extract keys only (Recommended)"
        description: "Prepare translation keys, humans translate later"
      - label: "Machine translation draft"
        description: "Use machine translation as placeholder"
      - label: "Keep English"
        description: "Prepare for translation but maintain English text"
    multiSelect: false

ON_LOCALE_FORMAT:

questions:
  - question: "Please select date/currency format style."
    header: "Locale"
    options:
      - label: "Follow browser settings (Recommended)"
        description: "Auto-detect user's locale"
      - label: "Match UI language"
        description: "Use format of selected language"
      - label: "ISO standard format"
        description: "Use region-independent standard format"
    multiSelect: false

ON_GLOSSARY_CHANGE:

questions:
  - question: "Glossary changes needed. How would you like to proceed?"
    header: "Glossary Change"
    options:
      - label: "Maintain existing terms (Recommended)"
        description: "Use current terms for consistency"
      - label: "Record new terms as proposal"
        description: "Document change proposal for later review"
      - label: "Update terminology"
        description: "Change to new terms project-wide"
    multiSelect: false

ON_RTL_SUPPORT:

questions:
  - question: "RTL (right-to-left) language support is needed. How would you like to proceed?"
    header: "RTL Support"
    options:
      - label: "Use CSS logical properties (Recommended)"
        description: "Use start/end for automatic flipping"
      - label: "RTL-specific stylesheet"
        description: "Manage RTL styles in separate CSS file"
      - label: "Handle later"
        description: "Support only LTR languages for now"
    multiSelect: false

I18N LIBRARY SETUP GUIDE

i18next + React Setup

npm install i18next react-i18next i18next-browser-languagedetector i18next-http-backend

// src/i18n/config.ts
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import LanguageDetector from 'i18next-browser-languagedetector';
import Backend from 'i18next-http-backend';

i18n
  .use(Backend)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: 'en',
    supportedLngs: ['en', 'ja', 'zh', 'ko'],
    debug: process.env.NODE_ENV === 'development',

    interpolation: {
      escapeValue: false, // React already escapes
    },

    // Namespace configuration
    ns: ['common', 'auth', 'errors'],
    defaultNS: 'common',

    // Backend configuration (load from /locales)
    backend: {
      loadPath: '/locales/{{lng}}/{{ns}}.json',
    },

    // Language detection order
    detection: {
      order: ['querystring', 'cookie', 'localStorage', 'navigator'],
      caches: ['localStorage', 'cookie'],
    },
  });

export default i18n;

// src/main.tsx
import './i18n/config';
import App from './App';

// Wrap with Suspense for async loading
<Suspense fallback={<LoadingSpinner />}>
  <App />
</Suspense>

// Usage in components
import { useTranslation } from 'react-i18next';

function MyComponent() {
  const { t, i18n } = useTranslation();

  return (
    <div>
      <h1>{t('welcome.title')}</h1>
      <p>{t('welcome.greeting', { name: 'John' })}</p>
      <button onClick={() => i18n.changeLanguage('ja')}>日本語</button>
    </div>
  );
}

// With namespace
function AuthComponent() {
  const { t } = useTranslation('auth');
  return <button>{t('login.submit')}</button>;
}

Next.js i18n Setup (App Router)

// next.config.js
module.exports = {
  // No i18n config needed for App Router
};

// src/i18n/settings.ts
export const fallbackLng = 'en';
export const languages = ['en', 'ja', 'zh', 'ko'];
export const defaultNS = 'common';

export function getOptions(lng = fallbackLng, ns = defaultNS) {
  return {
    supportedLngs: languages,
    fallbackLng,
    lng,
    fallbackNS: defaultNS,
    defaultNS,
    ns,
  };
}

// src/i18n/server.ts
import { createInstance } from 'i18next';
import resourcesToBackend from 'i18next-resources-to-backend';
import { initReactI18next } from 'react-i18next/initReactI18next';
import { getOptions } from './settings';

const initI18next = async (lng: string, ns: string) => {
  const i18nInstance = createInstance();
  await i18nInstance
    .use(initReactI18next)
    .use(resourcesToBackend((language: string, namespace: string) =>
      import(`../locales/${language}/${namespace}.json`)
    ))
    .init(getOptions(lng, ns));
  return i18nInstance;
};

export async function useTranslation(lng: string, ns?: string, options: { keyPrefix?: string } = {}) {
  const i18nextInstance = await initI18next(lng, ns || 'common');
  return {
    t: i18nextInstance.getFixedT(lng, ns, options.keyPrefix),
    i18n: i18nextInstance
  };
}

// src/app/[lng]/page.tsx
import { useTranslation } from '@/i18n/server';
import { languages } from '@/i18n/settings';

export async function generateStaticParams() {
  return languages.map((lng) => ({ lng }));
}

export default async function Page({ params: { lng } }: { params: { lng: string } }) {
  const { t } = await useTranslation(lng);

  return (
    <main>
      <h1>{t('welcome.title')}</h1>
    </main>
  );
}

react-intl Setup

npm install react-intl

// src/i18n/IntlProvider.tsx
import { IntlProvider } from 'react-intl';
import { useState, useEffect } from 'react';

import enMessages from '../locales/en.json';
import jaMessages from '../locales/ja.json';

const messages: Record<string, Record<string, string>> = {
  en: enMessages,
  ja: jaMessages,
};

export function AppIntlProvider({ children }: { children: React.ReactNode }) {
  const [locale, setLocale] = useState('en');

  useEffect(() => {
    const browserLocale = navigator.language.split('-')[0];
    if (messages[browserLocale]) {
      setLocale(browserLocale);
    }
  }, []);

  return (
    <IntlProvider
      locale={locale}
      messages={messages[locale]}
      defaultLocale="en"
      onError={(err) => {
        if (err.code !== 'MISSING_TRANSLATION') {
          console.error(err);
        }
      }}
    >
      {children}
    </IntlProvider>
  );
}

// Usage
import { FormattedMessage, useIntl } from 'react-intl';

function MyComponent() {
  const intl = useIntl();

  // Component-based
  return (
    <div>
      <FormattedMessage id="welcome.title" defaultMessage="Welcome" />
      <FormattedMessage
        id="welcome.greeting"
        defaultMessage="Hello, {name}!"
        values={{ name: 'John' }}
      />
    </div>
  );

  // Hook-based
  const title = intl.formatMessage({ id: 'welcome.title' });
}

vue-i18n Setup

npm install vue-i18n

// src/i18n/index.ts
import { createI18n } from 'vue-i18n';
import en from '../locales/en.json';
import ja from '../locales/ja.json';

export const i18n = createI18n({
  legacy: false, // Use Composition API
  locale: navigator.language.split('-')[0] || 'en',
  fallbackLocale: 'en',
  messages: { en, ja },
  numberFormats: {
    en: {
      currency: { style: 'currency', currency: 'USD' },
    },
    ja: {
      currency: { style: 'currency', currency: 'JPY' },
    },
  },
  datetimeFormats: {
    en: {
      short: { year: 'numeric', month: 'short', day: 'numeric' },
      long: { year: 'numeric', month: 'long', day: 'numeric', weekday: 'long' },
    },
    ja: {
      short: { year: 'numeric', month: 'short', day: 'numeric' },
      long: { year: 'numeric', month: 'long', day: 'numeric', weekday: 'long' },
    },
  },
});

<!-- Usage in Vue component -->
<template>
  <div>
    <h1>{{ t('welcome.title') }}</h1>
    <p>{{ t('welcome.greeting', { name: 'John' }) }}</p>
    <p>{{ n(1234.56, 'currency') }}</p>
    <p>{{ d(new Date(), 'long') }}</p>
  </div>
</template>

<script setup lang="ts">
import { useI18n } from 'vue-i18n';
const { t, n, d, locale } = useI18n();
</script>

INTL API PATTERNS

Date Formatting

// Basic date formatting
const date = new Date('2024-01-15T10:30:00');

// Short date
new Intl.DateTimeFormat('ja-JP').format(date);
// → "2024/1/15"

new Intl.DateTimeFormat('en-US').format(date);
// → "1/15/2024"

// Long date with options
new Intl.DateTimeFormat('ja-JP', {
  year: 'numeric',
  month: 'long',
  day: 'numeric',
  weekday: 'long',
}).format(date);
// → "2024年1月15日月曜日"

// Time
new Intl.DateTimeFormat('ja-JP', {
  hour: '2-digit',
  minute: '2-digit',
  hour12: false,
}).format(date);
// → "10:30"

// Date and time
new Intl.DateTimeFormat('ja-JP', {
  dateStyle: 'full',
  timeStyle: 'short',
}).format(date);
// → "2024年1月15日月曜日 10:30"

// Reusable formatter (better performance)
const dateFormatter = new Intl.DateTimeFormat('ja-JP', {
  year: 'numeric',
  month: 'short',
  day: 'numeric',
});
dateFormatter.format(date); // Use repeatedly

Number Formatting

const num = 1234567.89;

// Basic number
new Intl.NumberFormat('ja-JP').format(num);
// → "1,234,567.89"

new Intl.NumberFormat('de-DE').format(num);
// → "1.234.567,89"

// Currency
new Intl.NumberFormat('ja-JP', {
  style: 'currency',
  currency: 'JPY',
}).format(num);
// → "￥1,234,568"

new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
}).format(num);
// → "$1,234,567.89"

// Compact notation
new Intl.NumberFormat('en-US', {
  notation: 'compact',
  compactDisplay: 'short',
}).format(num);
// → "1.2M"

new Intl.NumberFormat('ja-JP', {
  notation: 'compact',
  compactDisplay: 'short',
}).format(num);
// → "123万"

// Percent
new Intl.NumberFormat('ja-JP', {
  style: 'percent',
  minimumFractionDigits: 1,
}).format(0.1234);
// → "12.3%"

// Units
new Intl.NumberFormat('ja-JP', {
  style: 'unit',
  unit: 'kilometer',
  unitDisplay: 'short',
}).format(100);
// → "100 km"

Relative Time

const rtf = new Intl.RelativeTimeFormat('ja-JP', {
  numeric: 'auto', // "yesterday" vs "1 day ago"
});

rtf.format(-1, 'day');    // → "昨日"
rtf.format(-2, 'day');    // → "2日前"
rtf.format(1, 'day');     // → "明日"
rtf.format(-1, 'hour');   // → "1時間前"
rtf.format(-30, 'minute'); // → "30分前"
rtf.format(-1, 'month');  // → "先月"
rtf.format(-1, 'year');   // → "去年"

// Always numeric
const rtfNumeric = new Intl.RelativeTimeFormat('ja-JP', {
  numeric: 'always',
});
rtfNumeric.format(-1, 'day'); // → "1日前"

// Helper function
function getRelativeTime(date: Date, locale: string = 'ja-JP'): string {
  const now = new Date();
  const diffMs = date.getTime() - now.getTime();
  const diffSecs = Math.round(diffMs / 1000);
  const diffMins = Math.round(diffSecs / 60);
  const diffHours = Math.round(diffMins / 60);
  const diffDays = Math.round(diffHours / 24);

  const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });

  if (Math.abs(diffSecs) < 60) return rtf.format(diffSecs, 'second');
  if (Math.abs(diffMins) < 60) return rtf.format(diffMins, 'minute');
  if (Math.abs(diffHours) < 24) return rtf.format(diffHours, 'hour');
  if (Math.abs(diffDays) < 30) return rtf.format(diffDays, 'day');
  if (Math.abs(diffDays) < 365) return rtf.format(Math.round(diffDays / 30), 'month');
  return rtf.format(Math.round(diffDays / 365), 'year');
}

List Formatting

const items = ['Apple', 'Banana', 'Cherry'];

// Conjunction (and)
new Intl.ListFormat('en-US', { type: 'conjunction' }).format(items);
// → "Apple, Banana, and Cherry"

new Intl.ListFormat('ja-JP', { type: 'conjunction' }).format(items);
// → "Apple、Banana、Cherry"

// Disjunction (or)
new Intl.ListFormat('en-US', { type: 'disjunction' }).format(items);
// → "Apple, Banana, or Cherry"

// Unit (no conjunction)
new Intl.ListFormat('en-US', { type: 'unit', style: 'narrow' }).format(items);
// → "Apple Banana Cherry"

// Short style
new Intl.ListFormat('en-US', { style: 'short', type: 'conjunction' }).format(items);
// → "Apple, Banana, & Cherry"

Plural Rules

// Determine plural category const pr = new Intl.PluralRules('en-US'); pr.select(0); // → "other" pr.select(1); // → "one" pr.select(2); // → "other"

const prJa = new Intl.PluralRules('ja-JP'); prJa.select(1); // → "other" (Japanese has no singular/plural distinction) prJa.select(2); // → "other"

// Ordinal (1st, 2nd, 3rd...) const prOrdinal = new Intl.PluralRules('en-US', { type: 'ordinal' <span class="token