@chipmobilesdk/rn-i18n 0.1.0

package/src/tooling/sync.ts

@@ -0,0 +1,198 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type {
+	LocaleSyncResult,
+	RuntimeEntryConfig,
+	SyncConfig,
+	TranslationTemplate,
+} from './types.ts';
+
+type JsonValue = string | { [key: string]: JsonValue };
+
+const PLURAL_CATEGORIES = new Set(['zero', 'one', 'two', 'few', 'many', 'other']);
+
+/**
+ * Mirrors the runtime plural-group leaf rule (translation/plurals.ts) so a
+ * plural variant object is synchronized as one key, not per category.
+ */
+function isPluralGroupValue(value: JsonValue): boolean {
+	if (typeof value !== 'object' || value === null) {
+		return false;
+	}
+	const keys = Object.keys(value);
+	return (
+		keys.length > 0 &&
+		'other' in value &&
+		keys.every(
+			key => PLURAL_CATEGORIES.has(key) && typeof value[key] === 'string',
+		)
+	);
+}
+
+/** Flattens nested locale JSON into dot-path keys with leaf values. */
+export function flattenTranslations(
+	node: JsonValue,
+	prefix = '',
+	into: Map<string, JsonValue> = new Map(),
+): Map<string, JsonValue> {
+	if (typeof node === 'string' || isPluralGroupValue(node)) {
+		into.set(prefix, node);
+		return into;
+	}
+	for (const [key, value] of Object.entries(node)) {
+		flattenTranslations(value, prefix ? `${prefix}.${key}` : key, into);
+	}
+	return into;
+}
+
+function sortValue(value: JsonValue): JsonValue {
+	if (typeof value === 'string') {
+		return value;
+	}
+	const sorted: { [key: string]: JsonValue } = {};
+	for (const key of Object.keys(value).sort((a, b) => a.localeCompare(b, 'en'))) {
+		sorted[key] = sortValue(value[key]);
+	}
+	return sorted;
+}
+
+/** Rebuilds the nested JSON object with deterministically sorted keys. */
+export function nestTranslations(flat: Map<string, JsonValue>): JsonValue {
+	const root: { [key: string]: JsonValue } = {};
+	const sortedKeys = [...flat.keys()].sort((a, b) => a.localeCompare(b, 'en'));
+	for (const flatKey of sortedKeys) {
+		const segments = flatKey.split('.');
+		let node = root;
+		for (let index = 0; index < segments.length - 1; index += 1) {
+			const segment = segments[index];
+			const next = node[segment];
+			if (typeof next !== 'object' || next === null || isPluralGroupValue(next)) {
+				node[segment] = {};
+			}
+			node = node[segment] as { [key: string]: JsonValue };
+		}
+		node[segments[segments.length - 1]] = sortValue(flat.get(flatKey)!);
+	}
+	return root;
+}
+
+function placeholderValue(
+	config: SyncConfig,
+	locale: string,
+	key: string,
+	defaultText: string | undefined,
+): string {
+	const placeholder = config.placeholder ?? 'template';
+	if (placeholder === 'template') {
+		return defaultText ?? key;
+	}
+	if (typeof placeholder === 'string') {
+		return placeholder;
+	}
+	return placeholder[locale] ?? defaultText ?? key;
+}
+
+function writeLocaleFile(filePath: string, content: JsonValue): void {
+	// Atomic per-file write: a failed run never leaves a partial locale file.
+	const json = `${JSON.stringify(content, null, '\t')}\n`;
+	const temporaryPath = `${filePath}.tmp`;
+	fs.writeFileSync(temporaryPath, json, 'utf8');
+	fs.renameSync(temporaryPath, filePath);
+}
+
+/**
+ * Synchronizes every configured locale JSON file against the scanned
+ * template: creates missing files, adds missing keys with the configured
+ * placeholder, preserves existing translations verbatim, removes stale keys,
+ * and protects declared runtime-only entries (FR-027…FR-030, FR-034/FR-035).
+ * Conflicted keys are never added or overwritten while the conflict is open.
+ */
+export function syncLocaleFiles(
+	rootDir: string,
+	config: SyncConfig,
+	template: TranslationTemplate,
+	runtimeEntries: readonly RuntimeEntryConfig[],
+): LocaleSyncResult[] {
+	const templateByKey = new Map(template.keys.map(key => [key.key, key]));
+	const conflictedKeys = new Set(template.conflicts.map(conflict => conflict.key));
+	const runtimeByKey = new Map(runtimeEntries.map(entry => [entry.key, entry]));
+	const results: LocaleSyncResult[] = [];
+
+	for (const locale of config.locales) {
+		const filePath = path.join(rootDir, config.localesDir, `${locale}.json`);
+		const result: LocaleSyncResult = {
+			locale,
+			filePath,
+			created: false,
+			addedKeys: [],
+			preservedKeys: [],
+			removedKeys: [],
+			runtimePreserved: [],
+			runtimeAdded: [],
+			runtimeReported: [],
+		};
+		results.push(result);
+
+		let existing = new Map<string, JsonValue>();
+		if (fs.existsSync(filePath)) {
+			try {
+				const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8')) as JsonValue;
+				existing = flattenTranslations(parsed);
+			} catch (error) {
+				result.error = `Malformed locale file ${locale}.json: ${String(error)}`;
+				continue;
+			}
+		} else {
+			result.created = true;
+		}
+
+		const next = new Map<string, JsonValue>();
+
+		for (const [key, templateKey] of templateByKey) {
+			const current = existing.get(key);
+			if (current !== undefined) {
+				next.set(key, current);
+				result.preservedKeys.push(key);
+				continue;
+			}
+			if (conflictedKeys.has(key)) {
+				// Reported for manual review; never silently added (FR-031).
+				continue;
+			}
+			next.set(
+				key,
+				placeholderValue(config, locale, key, templateKey.defaultText),
+			);
+			result.addedKeys.push(key);
+		}
+
+		for (const [key, entry] of runtimeByKey) {
+			const current = existing.get(key);
+			if (current !== undefined) {
+				next.set(key, current);
+				result.runtimePreserved.push(key);
+				continue;
+			}
+			if ((entry.policy ?? 'report') === 'add') {
+				next.set(key, placeholderValue(config, locale, key, entry.defaultText));
+				result.runtimeAdded.push(key);
+			} else {
+				result.runtimeReported.push(key);
+			}
+		}
+
+		for (const key of existing.keys()) {
+			if (!next.has(key) && !runtimeByKey.has(key) && !conflictedKeys.has(key)) {
+				result.removedKeys.push(key);
+			}
+		}
+
+		fs.mkdirSync(path.dirname(filePath), { recursive: true });
+		writeLocaleFile(filePath, nestTranslations(next));
+		result.addedKeys.sort((a, b) => a.localeCompare(b, 'en'));
+		result.preservedKeys.sort((a, b) => a.localeCompare(b, 'en'));
+		result.removedKeys.sort((a, b) => a.localeCompare(b, 'en'));
+	}
+
+	return results;
+}

package/src/tooling/types.ts

@@ -0,0 +1,119 @@
+/**
+ * Shared contracts for the Node-only extraction and synchronization tooling.
+ * This module must stay free of React Native imports; it is consumed through
+ * the `@chipmobilesdk/rn-i18n/tooling` entrypoint and the CLI.
+ */
+
+export interface PatternConfig {
+	/**
+	 * Regex source with a named `key` capture group for statically resolvable
+	 * keys, and an optional named `defaultText` group for template values.
+	 */
+	regex: string;
+	/** Extra regex flags; `g` is always applied. */
+	flags?: string;
+	/**
+	 * Optional regex matching dynamic usages of the same call style. Matches
+	 * that do not overlap a static key match are reported as ambiguous.
+	 */
+	ambiguousRegex?: string;
+}
+
+export interface SyncConfig {
+	/** Globs relative to the project root, e.g. `src/**\/*.{ts,tsx}`. */
+	sourceGlobs: string[];
+	patterns: PatternConfig[];
+	/** Directory containing `<locale>.json` files. */
+	localesDir: string;
+	locales: string[];
+	/** Module exporting the declared runtime-only entries. */
+	runtimeEntriesFile?: string;
+	/**
+	 * Value written for newly added keys: `template` uses the discovered
+	 * default text (falling back to the key), a string is used verbatim, and
+	 * a map selects per locale. Default: `template`.
+	 */
+	placeholder?: 'template' | string | Record<string, string>;
+	/** Optional JSON report output path. */
+	reportPath?: string;
+	/** Generated typed key artifact path, e.g. `src/i18n/keys.generated.ts`. */
+	generateKeysFile?: string;
+	/** Exported key type name. Default: `AppI18nKey`. */
+	keysTypeName?: string;
+}
+
+export interface RuntimeEntryConfig {
+	key: string;
+	defaultText: string;
+	policy?: 'add' | 'report';
+	description?: string;
+}
+
+export interface SourceLocation {
+	file: string;
+	line: number;
+}
+
+export interface TemplateKey {
+	key: string;
+	defaultText?: string;
+	locations: SourceLocation[];
+}
+
+export interface AmbiguousUsage {
+	file: string;
+	line: number;
+	snippet: string;
+}
+
+export interface KeyConflict {
+	key: string;
+	values: { text: string; location: SourceLocation }[];
+}
+
+export interface TranslationTemplate {
+	/** Discovered keys sorted by key name. */
+	keys: TemplateKey[];
+	ambiguous: AmbiguousUsage[];
+	conflicts: KeyConflict[];
+	scannedFiles: number;
+}
+
+export interface LocaleSyncResult {
+	locale: string;
+	filePath: string;
+	created: boolean;
+	addedKeys: string[];
+	preservedKeys: string[];
+	removedKeys: string[];
+	runtimePreserved: string[];
+	runtimeAdded: string[];
+	runtimeReported: string[];
+	/** Set when the locale file is malformed; no write happened. */
+	error?: string;
+}
+
+export type ReportOutcome = 'success' | 'completedWithWarnings' | 'failed';
+
+export interface ExtractionReport {
+	outcome: ReportOutcome;
+	discovered: {
+		key: string;
+		defaultText?: string;
+		locations: string[];
+	}[];
+	createdLocaleFiles: { locale: string; filePath: string }[];
+	addedKeys: Record<string, string[]>;
+	preservedKeys: Record<string, string[]>;
+	removedStaleKeys: Record<string, string[]>;
+	missingPerLocale: Record<string, string[]>;
+	runtimeOnly: {
+		declared: string[];
+		preserved: Record<string, string[]>;
+		added: Record<string, string[]>;
+		reported: Record<string, string[]>;
+	};
+	ambiguous: AmbiguousUsage[];
+	conflicts: KeyConflict[];
+	errors: string[];
+}

package/src/translation/interpolate.ts

@@ -0,0 +1,23 @@
+import type { TranslateVars } from '../config/types';
+
+const VARIABLE_PATTERN = /\{\{\s*([\w.]+)\s*\}\}/g;
+
+/**
+ * Replaces `{{name}}` placeholders with named values. Missing variables keep
+ * their placeholder text so the result stays deterministic, and each missing
+ * name is reported through `onMissingVariable`.
+ */
+export function interpolate(
+	text: string,
+	vars?: TranslateVars,
+	onMissingVariable?: (name: string) => void,
+): string {
+	return text.replace(VARIABLE_PATTERN, (placeholder, name: string) => {
+		const value = vars?.[name];
+		if (value === undefined || value === null) {
+			onMissingVariable?.(name);
+			return placeholder;
+		}
+		return String(value);
+	});
+}

package/src/translation/plurals.ts

@@ -0,0 +1,69 @@
+import type {
+	LocaleConfig,
+	PluralCategory,
+	PluralRule,
+	TranslationNode,
+} from '../config/types';
+
+export const PLURAL_CATEGORIES: readonly PluralCategory[] = [
+	'zero',
+	'one',
+	'two',
+	'few',
+	'many',
+	'other',
+];
+
+const oneOtherRule: PluralRule = count => (count === 1 ? 'one' : 'other');
+const otherOnlyRule: PluralRule = () => 'other';
+
+/**
+ * Package-owned plural rules. Intl.PluralRules is not implemented by Hermes,
+ * so rules are resolved from configuration to keep behavior identical across
+ * devices and test environments. Languages without a built-in rule use the
+ * documented default (`count === 1` selects `one`, everything else `other`)
+ * unless the locale configuration supplies a custom rule.
+ */
+const BUILT_IN_RULES: Record<string, PluralRule> = {
+	en: oneOtherRule,
+	ja: otherOnlyRule,
+	vi: otherOnlyRule,
+};
+
+export const DEFAULT_PLURAL_RULE: PluralRule = oneOtherRule;
+
+export function resolvePluralRule(locale: LocaleConfig): PluralRule {
+	if (locale.pluralRule) {
+		return locale.pluralRule;
+	}
+	const language = locale.code.split('-')[0]?.toLowerCase() ?? '';
+	return BUILT_IN_RULES[language] ?? DEFAULT_PLURAL_RULE;
+}
+
+/**
+ * A plural group is an object whose keys are all plural categories, whose
+ * values are all strings, and which provides the required `other` variant.
+ */
+export function isPluralGroup(
+	node: TranslationNode,
+): node is Record<string, string> {
+	if (typeof node !== 'object' || node === null) {
+		return false;
+	}
+	const keys = Object.keys(node);
+	if (keys.length === 0 || !('other' in node)) {
+		return false;
+	}
+	return keys.every(
+		key =>
+			(PLURAL_CATEGORIES as readonly string[]).includes(key) &&
+			typeof (node as Record<string, unknown>)[key] === 'string',
+	);
+}
+
+export function selectPluralVariant(
+	group: Record<string, string>,
+	category: PluralCategory,
+): string {
+	return group[category] ?? group.other;
+}

package/src/translation/resolver.ts

@@ -0,0 +1,146 @@
+import type {
+	LocaleConfig,
+	MissingTranslationPolicy,
+	TranslateOptions,
+	TranslateVars,
+	TranslationNamespace,
+	TranslationNode,
+	TranslationResources,
+} from '../config/types';
+import { interpolate } from './interpolate';
+import { isPluralGroup, resolvePluralRule, selectPluralVariant } from './plurals';
+import type { RuntimeEntryRegistry } from './runtimeKeys';
+
+export interface ResolverContext {
+	localesByCode: ReadonlyMap<string, LocaleConfig>;
+	resources: TranslationResources;
+	runtimeEntries: RuntimeEntryRegistry;
+	missingTranslation: MissingTranslationPolicy;
+	/** Dedupe set so each failed lookup path warns exactly once. */
+	warned: Set<string>;
+}
+
+export function warnOnce(
+	warned: Set<string>,
+	dedupeKey: string,
+	message: string,
+): void {
+	if (warned.has(dedupeKey)) {
+		return;
+	}
+	warned.add(dedupeKey);
+	console.warn(message);
+}
+
+/** Walks a dot-path key through a nested translation namespace. */
+export function getTranslationNode(
+	namespace: TranslationNamespace | undefined,
+	key: string,
+): TranslationNode | undefined {
+	if (!namespace) {
+		return undefined;
+	}
+	let node: TranslationNode = namespace;
+	for (const segment of key.split('.')) {
+		if (typeof node !== 'object' || node === null) {
+			return undefined;
+		}
+		const next: TranslationNode | undefined = node[segment];
+		if (next === undefined) {
+			return undefined;
+		}
+		node = next;
+	}
+	return node;
+}
+
+function pickValue(
+	node: TranslationNode,
+	locale: LocaleConfig,
+	options: TranslateOptions | undefined,
+	warned: Set<string>,
+	key: string,
+): string | undefined {
+	if (typeof node === 'string') {
+		return node;
+	}
+	if (isPluralGroup(node)) {
+		const count = options?.count;
+		if (count === undefined) {
+			return node.other;
+		}
+		return selectPluralVariant(node, resolvePluralRule(locale)(count));
+	}
+	warnOnce(
+		warned,
+		`invalid-value|${locale.code}|${key}`,
+		`[rn-i18n] Translation value for "${key}" in locale "${locale.code}" is not text or a plural group; treating it as missing.`,
+	);
+	return undefined;
+}
+
+/**
+ * Resolves a key through the active locale, its ordered fallback chain, and
+ * declared runtime-only default text, applying plural selection and named
+ * variable interpolation. Misses are reported with one console warning per
+ * lookup path; a full-chain miss applies the configured missing-translation
+ * policy (FR-008…FR-011, FR-033).
+ */
+export function translate(
+	context: ResolverContext,
+	activeCode: string,
+	key: string,
+	vars?: TranslateVars,
+	options?: TranslateOptions,
+): string {
+	const active = context.localesByCode.get(activeCode);
+	const chain = [activeCode, ...(active?.fallbackChain ?? [])];
+	const mergedVars: TranslateVars | undefined =
+		options?.count === undefined ? vars : { count: options.count, ...vars };
+
+	const interpolateWith = (text: string, sourceLocale: string) =>
+		interpolate(text, mergedVars, name =>
+			warnOnce(
+				context.warned,
+				`missing-var|${sourceLocale}|${key}|${name}`,
+				`[rn-i18n] Missing interpolation variable "${name}" for key "${key}" in locale "${sourceLocale}".`,
+			),
+		);
+
+	for (const code of chain) {
+		const locale = context.localesByCode.get(code);
+		if (!locale) {
+			continue;
+		}
+		const node = getTranslationNode(context.resources[code], key);
+		if (node === undefined) {
+			continue;
+		}
+		const value = pickValue(node, locale, options, context.warned, key);
+		if (value === undefined) {
+			continue;
+		}
+		if (code !== activeCode) {
+			warnOnce(
+				context.warned,
+				`fallback|${activeCode}|${key}`,
+				`[rn-i18n] Key "${key}" is missing in locale "${activeCode}"; served from fallback locale "${code}".`,
+			);
+		}
+		return interpolateWith(value, code);
+	}
+
+	const runtimeEntry = context.runtimeEntries.get(key);
+	if (runtimeEntry) {
+		return interpolateWith(runtimeEntry.defaultText, activeCode);
+	}
+
+	warnOnce(
+		context.warned,
+		`missing|${activeCode}|${key}`,
+		`[rn-i18n] Missing translation for key "${key}" in locale "${activeCode}" and its entire fallback chain.`,
+	);
+	return context.missingTranslation.mode === 'placeholder'
+		? context.missingTranslation.text
+		: key;
+}

package/src/translation/runtimeKeys.ts

@@ -0,0 +1,27 @@
+import type { RuntimeTranslationEntry } from '../config/types';
+
+/**
+ * Registry of declared runtime-only translation entries. Entries participate
+ * in the same lookup pipeline as scanned template keys and are protected from
+ * removal during locale JSON synchronization.
+ */
+export type RuntimeEntryRegistry = Map<string, RuntimeTranslationEntry>;
+
+export function createRuntimeRegistry(
+	entries?: readonly RuntimeTranslationEntry[],
+): RuntimeEntryRegistry {
+	const registry: RuntimeEntryRegistry = new Map();
+	if (entries) {
+		registerRuntimeEntries(registry, entries);
+	}
+	return registry;
+}
+
+export function registerRuntimeEntries(
+	registry: RuntimeEntryRegistry,
+	entries: readonly RuntimeTranslationEntry[],
+): void {
+	for (const entry of entries) {
+		registry.set(entry.key, entry);
+	}
+}