国际化与本地化测试：文案抽取、复数与性别规则、RTL 布局、时区与伪本地化

层次一：静态层   —— 硬编码扫描、缺失翻译、占位符一致性
层次二：单元层   —— 格式化函数、复数规则、日期/数字
层次三：组件层   —— 文本渲染、RTL 镜像、溢出
层次四：视觉层   —— 伪本地化 + 截图对比
层次五：端到端层 —— 切换语言/时区的完整用户旅程

// 反模式：文案硬编码
<button>Submit</button>
<button title="Close">×</button>

// 正确：全部走翻译函数
<button>{t("common.submit")}</button>
<button title={t("common.close")}>×</button>

// eslint-plugin-i18next：把硬编码变成 lint 错误
// .eslintrc.js
module.exports = {
  plugins: ["i18next"],
  rules: {
    "i18next/no-literal-string": ["error", {
      markupOnly: true,
      ignoreAttribute: ["data-testid", "className", "to", "href"],
    }],
  },
};

# 运行后直接报出所有硬编码位置
npx eslint src/ --rule '{"i18next/no-literal-string": "error"}'
# src/Checkout.tsx
#   12:5  error  string literal "Place Order" is not internationalized

// en.json
{ "cart.items": "You have {count} items in your cart" }
// zh.json（错误：占位符名被改了）
{ "cart.items": "您的购物车有 {total} 件商品" }

# 占位符一致性校验器
import json, re, sys

PLACEHOLDER = re.compile(r"\{(\w+)\}")

def placeholders(text):
    return set(PLACEHOLDER.findall(text))

def check(base_file, target_files):
    base = json.load(open(base_file))
    errors = []
    for tf in target_files:
        target = json.load(open(tf))
        for key, base_text in base.items():
            if key not in target:
                errors.append(f"{tf}: 缺失 key {key}")
                continue
            bp, tp = placeholders(base_text), placeholders(target[key])
            if bp != tp:
                errors.append(
                    f"{tf}: {key} 占位符不一致 base={sorted(bp)} target={sorted(tp)}")
    return errors

if __name__ == "__main__":
    errs = check("locales/en.json", ["locales/zh.json", "locales/ja.json"])
    for e in errs:
        print("✖", e)
    sys.exit(1 if errs else 0)

# 用 i18next-parser 检查 key 覆盖率
npx i18next-parser --fail-on-warnings
# 报告：未使用的 key（代码删了文案没删）与缺失的 key（代码用了但没翻译）

def test_no_missing_translations():
    base = json.load(open("locales/en.json"))
    for locale in ["zh", "ja", "de", "ar"]:
        target = json.load(open(f"locales/{locale}.json"))
        missing = set(base) - set(target)
        assert not missing, f"{locale} 缺失翻译: {sorted(missing)[:10]}"

def test_no_orphan_keys():
    # 扫描代码里实际用到的 key，反向检查是否有从未使用的翻译
    used = scan_source_for_t_keys("src/")
    defined = set(json.load(open("locales/en.json")))
    orphan = defined - used
    # 孤儿 key 不是错误，但要定期清理
    assert len(orphan) < 50, f"孤儿翻译过多: {len(orphan)}"

// i18next 用 Intl.PluralRules 自动选择复数形式
// locales/ru.json
{
  "cart.items_one": "{{count}} товар",
  "cart.items_few": "{{count}} товара",
  "cart.items_many": "{{count}} товаров",
  "cart.items_other": "{{count}} товара"
}

// 测试：验证各语言的复数选择正确
import { IntlPluralRules } from "intl-pluralrules";

const cases = [
  { locale: "en", count: 1, expect: "one" },
  { locale: "en", count: 2, expect: "other" },
  { locale: "ru", count: 1, expect: "one" },
  { locale: "ru", count: 2, expect: "few" },
  { locale: "ru", count: 5, expect: "many" },
  { locale: "ar", count: 0, expect: "zero" },
  { locale: "ar", count: 2, expect: "two" },
  { locale: "zh", count: 5, expect: "other" },
];

test.each(cases)("$locale 复数 $count → $expect", ({ locale, count, expect }) => {
  const pr = new Intl.PluralRules(locale);
  expect(pr.select(count)).toBe(expect);
});

# 用 babel 验证复数规则
from babel.core import Locale

def test_plural_rules():
    cases = [("ru", 1, "one"), ("ru", 2, "few"), ("ru", 5, "many"),
             ("ar", 0, "zero"), ("ar", 2, "two"), ("zh", 5, "other")]
    for loc, n, expect in cases:
        rules = Locale(loc).plural_form
        assert rules(n) == expect, f"{loc}({n}) = {rules(n)}, want {expect}"

// 反模式：拼接句子（语序被写死）
{ "message": "Hi " + name + ", you have " + count + " new messages" }

// 正确：整句参数化，让翻译者决定语序
{ "message": "Hi {name}, you have {count} new messages" }
// 日语翻译可自由调整语序：{name}さん、新着メッセージが{count}件あります

def test_no_string_concatenation_in_i18n():
    # 扫描源码，检测 "t(...) + " 这类拼接（破坏语序）
    import re, pathlib
    bad = []
    for f in pathlib.Path("src").rglob("*.tsx"):
        for i, line in enumerate(f.read_text().splitlines(), 1):
            if re.search(r"\bt\([^)]*\)\s*\+", line):
                bad.append(f"{f}:{i}: {line.strip()}")
    assert not bad, "检测到 i18n 字符串拼接（破坏语序）:\n" + "\n".join(bad)

/* 反模式：物理属性，RTL 下错位 */
.card { margin-left: 16px; padding-right: 8px; text-align: left; }

/* 正确：逻辑属性，自动随书写方向镜像 */
.card {
  margin-inline-start: 16px;   /* LTR 左，RTL 右 */
  padding-inline-end: 8px;
  text-align: start;           /* LTR 左，RTL 右 */
}

<!-- dir 属性驱动整页镜像 -->
<html lang="ar" dir="rtl">

// 测试：断言 RTL 下关键元素的逻辑位置
test("RTL 下图标应出现在文字右侧", async ({ page }) => {
  await page.goto("/ar");
  const icon = page.locator(".button-icon");
  const label = page.locator(".button-label");
  const iconBox = await icon.boundingBox();
  const labelBox = await label.boundingBox();
  // RTL 下图标应在标签右边
  expect(iconBox.x).toBeGreaterThan(labelBox.x);
});

test("RTL 下不应有水平滚动条", async ({ page }) => {
  await page.goto("/ar");
  const overflow = await page.evaluate(
    () => document.documentElement.scrollWidth > document.documentElement.clientWidth);
  expect(overflow).toBe(false);
});

// 测试：按钮文本不得溢出容器
test("长语言下按钮不截断", async ({ page }) => {
  await page.goto("/de");
  const btn = page.locator(".primary-button");
  const overflowed = await btn.evaluate((el) => el.scrollWidth > el.clientWidth + 1);
  expect(overflowed).toBe(false);
});

// 伪本地化转换：a → à, 并加长 40%，用括号包裹
function pseudo(text) {
  const map = { a: "à", e: "é", i: "î", o: "ô", u: "û", c: "ç", n: "ñ" };
  const accented = text.replace(/[aeiouc n]/g, (ch) => map[ch] || ch);
  return `[${accented}${"·".repeat(Math.ceil(text.length * 0.4))}]`;
}
// "Submit" → "[Sùbmît···]"

# 用 i18next-pseudo 或框架内置的 pseudo-locale
# 优点：不翻译也能测，且立刻暴露硬编码（硬编码文字不会变）

// 反模式：用本地时区解析
new Date("2026-01-01");        // 在 UTC-5 会变成 2025-12-31T19:00
new Date("2026-01-01T00:00:00"); // 同上，按本地时区解释

// 正确：显式带时区或只用日期部分
new Date("2026-01-01T00:00:00Z");      // 明确 UTC
new Date(2026, 0, 1);                   // 本地日期（无时区歧义）

def test_date_not_shifted_across_timezones():
    import os, time
    from datetime import date
    # 同一逻辑日期，在不同 TZ 下应一致
    for tz in ["UTC", "America/New_York", "Asia/Tokyo"]:
        os.environ["TZ"] = tz
        time.tzset()
        d = parse_user_date("2026-01-01")     # 业务函数
        assert d == date(2026, 1, 1), f"{tz} 下日期偏移为 {d}"

// Playwright 里指定时区做端到端测试
test.use({ timezoneId: "Asia/Shanghai" });
test("订单日期按用户时区显示", async ({ page }) => {
  await page.goto("/orders");
  await expect(page.locator(".order-date")).toHaveText("2026-01-01 08:00");
});

// 反模式：手写格式化
`${y}-${m}-${d}`;                    // 顺序写死，美国是 MM/DD/YYYY
`$${amount.toFixed(2)}`;             // 货币符号写死

// 正确：Intl API
new Intl.DateTimeFormat("en-US").format(d);   // 1/1/2026
new Intl.DateTimeFormat("de-DE").format(d);   // 1.1.2026
new Intl.NumberFormat("de-DE").format(1234.5); // 1.234,5（逗号是小数点！）
new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format(1234.5);
// $1,234.50

from babel.numbers import format_currency, format_decimal
from babel.dates import format_date

def test_number_and_date_formats():
    # 德语：千分位是点，小数点是逗号
    assert format_decimal(1234.5, locale="de_DE") == "1.234,5"
    assert format_decimal(1234.5, locale="en_US") == "1,234.5"
    # 日期顺序因区域而异
    assert format_date(__import__("datetime").date(2026, 1, 1), locale="en_US") == "Jan 1, 2026"
    assert format_date(__import__("datetime").date(2026, 1, 1), locale="de_DE") == "1. Jan. 2026"

jobs:
  i18n-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - name: 硬编码扫描
        run: npx eslint src/ --rule '{"i18next/no-literal-string": "error"}'
      - name: 占位符一致性
        run: python scripts/check_placeholders.py
      - name: 缺失翻译
        run: python scripts/check_missing_translations.py
      - name: 复数规则
        run: npx jest tests/i18n/plural.test.js
      - name: 伪本地化视觉回归
        run: npx playwright test --project=pseudo-locale
      - name: RTL 布局断言
        run: npx playwright test --project=rtl

// playwright.config.js：为每种语言跑一套视觉回归
const locales = ["en", "de", "ja", "ar", "zh"];
export default {
  projects: locales.map((locale) => ({
    name: `visual-${locale}`,
    use: { locale, timezoneId: "Asia/Shanghai" },
  })),
};

test("首页在目标语言下布局稳定", async ({ page }, testInfo) => {
  await page.goto("/");
  // 每种语言独立快照，任何语言的布局回退都会被抓到
  await expect(page).toHaveScreenshot(`home-${testInfo.project.name}.png`);
});