zebbern/claude-code-guide / skills/localization-toolkit
localization-toolkit
VerifiedThis skill should be used when setting up, auditing, or enforcing internationalization/localization in UI codebases (React/TS, i18next or similar, JSON locales), including installing/configuring the i18n framework, replacing hard-coded strings, ensuring en-US/zh-CN coverage, mapping error codes to localized messages, and validating key parity, pluralization, and formatting.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 1.0 KB |
| SKILL.md | skill md | 5.1 KB |
| scripts/i18n_audit.py | script | 4.8 KB |
scripts/i18n_audit.py
View on GitHub#!/usr/bin/env python3
"""Audit i18n key usage vs locale JSON files.
Usage:
python scripts/i18n_audit.py --src ./src --locale ./locales/en-US/common.json --locale ./locales/zh-CN/common.json
"""
from __future__ import annotations
import argparse
import json
import re
import sys
from pathlib import Path
from typing import Dict, Iterable, List, Set
KEY_PATTERNS = [
re.compile(r"(?<![\w.])t\(\s*['\"]([^'\"]+)['\"]"),
re.compile(r"\bi18n\.t\(\s*['\"]([^'\"]+)['\"]"),
re.compile(r"\bi18next\.t\(\s*['\"]([^'\"]+)['\"]"),
]
PLURAL_SUFFIXES = ("_zero", "_one", "_two", "_few", "_many", "_other")
def iter_source_files(root: Path, exts: Iterable[str]) -> Iterable[Path]:
for path in root.rglob("*"):
if path.is_dir():
continue
if "node_modules" in path.parts or ".git" in path.parts:
continue
if path.suffix.lstrip(".") in exts:
yield path
def extract_keys(paths: Iterable[Path]) -> Set[str]:
keys: Set[str] = set()
for path in paths:
try:
text = path.read_text(encoding="utf-8")
except UnicodeDecodeError:
continue
for pattern in KEY_PATTERNS:
for match in pattern.finditer(text):
keys.add(match.group(1))
return keys
def flatten_json(obj, prefix: str = "") -> Dict[str, object]:
keys: Dict[str, object] = {}
if isinstance(obj, dict):
for key, value in obj.items():
path = f"{prefix}.{key}" if prefix else key
keys.update(flatten_json(value, path))
else:
keys[prefix] = obj
return keys
def locale_name(path: Path) -> str:
name = path.stem
if path.name in {"common.json", "translation.json", "messages.json"}:
parent = path.parent.name
if parent:
return parent
return name
def has_plural_variant(key: str, key_set: Set[str]) -> bool:
return any(f"{key}{suffix}" in key_set for suffix in PLURAL_SUFFIXES)
def load_locale(path: Path) -> Set[str]:
with path.open(encoding="utf-8") as handle:
data = json.load(handle)
return set(flatten_json(data).keys())
def compute_missing(used: Set[str], locale_keys: Set[str]) -> List[str]:
missing = []
for key in sorted(used):
if key in locale_keys:
continue
if has_plural_variant(key, locale_keys):
continue
missing.append(key)
return missing
def main() -> int:
parser = argparse.ArgumentParser(description="Audit i18n keys against locale JSON files.")
parser.add_argument("--src", default=".", help="Source root to scan")
parser.add_argument(
"--locale",
action="append",
required=True,
help="Path to locale JSON (repeatable)",
)
parser.add_argument(
"--ext",
action="append",
default=["ts", "tsx", "js", "jsx"],
help="File extensions to scan (repeatable)",
)
parser.add_argument("--json", action="store_true", help="Emit JSON output")
args = parser.parse_args()
src_root = Path(args.src).resolve()
locale_paths = [Path(p).resolve() for p in args.locale]
source_files = list(iter_source_files(src_root, args.ext))
used_keys = extract_keys(source_files)
locale_key_map: Dict[str, Set[str]] = {}
for path in locale_paths:
locale_key_map[locale_name(path)] = load_locale(path)
missing_by_locale = {
name: compute_missing(used_keys, keys) for name, keys in locale_key_map.items()
}
unused_by_locale = {
name: sorted(keys - used_keys) for name, keys in locale_key_map.items()
}
parity_missing: Dict[str, List[str]] = {}
locale_names = list(locale_key_map.keys())
for name in locale_names:
other_names = [n for n in locale_names if n != name]
other_keys = set().union(*(locale_key_map[n] for n in other_names))
parity_missing[name] = sorted(other_keys - locale_key_map[name])
output = {
"used_keys": sorted(used_keys),
"missing_by_locale": missing_by_locale,
"unused_by_locale": unused_by_locale,
"parity_missing": parity_missing,
}
if args.json:
json.dump(output, sys.stdout, indent=2, ensure_ascii=False)
sys.stdout.write("\n")
return 0
print(f"Scanned {len(source_files)} files")
print(f"Used keys: {len(used_keys)}")
for name in locale_names:
missing = missing_by_locale[name]
unused = unused_by_locale[name]
parity = parity_missing[name]
print(f"\nLocale: {name}")
print(f" Missing: {len(missing)}")
for key in missing[:50]:
print(f" - {key}")
if len(missing) > 50:
print(" ...")
print(f" Unused: {len(unused)}")
print(f" Parity missing: {len(parity)}")
return 0
if __name__ == "__main__":
raise SystemExit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |