@gtcx/i18n 0.1.0

package/README.md

@@ -0,0 +1,104 @@
+# @gtcx/i18n
+
+Multi-language support system for GTCX Protocol — country-agnostic internationalization with cultural adaptation.
+
+## Features
+
+- **50+ Languages** — Primary and local dialect support
+- **Cultural Context** — Language that feels native, not translated
+- **Offline-First** — Full i18n capabilities without connectivity
+- **AI-Native** — Agents auto-detect and adapt to user language
+- **RTL Support** — Right-to-left language handling
+
+## Installation
+
+```bash
+pnpm add @gtcx/i18n
+```
+
+## Usage
+
+```typescript
+import { I18nService, CulturalContext } from '@gtcx/i18n';
+
+// Initialize with country context
+const i18n = new I18nService({
+  country: 'ghana',
+  primaryLanguage: 'en',
+  localLanguages: ['tw', 'gaa', 'ee'], // Twi, Ga, Ewe
+  fallbackLanguage: 'en',
+});
+
+// Translate with cultural context
+const message = i18n.t('compliance.violation_warning', {
+  context: 'formal', // Adapts tone for authority figures
+  dialect: 'tw', // Twi dialect
+});
+
+// AI agent language detection
+const detectedLang = await i18n.detectLanguage(userInput);
+const response = i18n.t('welcome', { lang: detectedLang });
+```
+
+## Cultural Adaptation
+
+The i18n system goes beyond translation:
+
+```typescript
+// Cultural context affects more than words
+const culturalContext = i18n.getCulturalContext('ghana');
+
+culturalContext.communicationStyle; // 'formal', 'community-oriented'
+culturalContext.decisionMaking; // 'consensus', 'elder-consultation'
+culturalContext.honorifics; // true (use respectful titles)
+culturalContext.traditionalKnowledge; // Integration points
+```
+
+## Supported Languages by Region
+
+### West Africa
+
+- English, Twi, Ga, Ewe, Dagbani (Ghana)
+- English, Yoruba, Igbo, Hausa (Nigeria)
+- French, Wolof (Senegal)
+
+### East Africa
+
+- Swahili, English, Kikuyu, Luo (Kenya)
+- Swahili, English, Sukuma (Tanzania)
+
+### Latin America
+
+- Spanish, Quechua, Aymara (Peru)
+- Spanish, Wayuu, Emberá (Colombia)
+
+### Global
+
+- English, French, Spanish, Portuguese, Arabic, Chinese, Hindi
+
+## Architecture
+
+```
+packages/i18n/
+├── src/
+│   ├── index.ts           # Main exports
+│   ├── service.ts         # I18nService class
+│   ├── cultural-context.ts # Cultural adaptation logic
+│   ├── language-detector.ts # AI language detection
+│   ├── offline-store.ts   # Offline translation cache
+│   └── types.ts           # TypeScript definitions
+├── locales/               # Translation files
+│   ├── en/
+│   ├── sw/                # Swahili
+│   ├── es/                # Spanish
+│   └── ...
+└── cultural/              # Cultural context configs
+    ├── ghana.yaml
+    ├── kenya.yaml
+    └── ...
+```
+
+## Related Packages
+
+- `@gtcx/accessibility` — Tech literacy and WCAG compliance
+- `@gtcx/offline-sync` — Offline-first data synchronization

package/dist/index.d.mts

@@ -0,0 +1,374 @@
+/**
+ * Type definitions for @gtcx/i18n
+ */
+interface LanguageConfig {
+    /** ISO 639-1 language code */
+    code: string;
+    /** Language name in English */
+    name: string;
+    /** Language name in native script */
+    nativeName: string;
+    /** Countries where this language is used */
+    countries: string[];
+    /** Writing system (latin, arabic, devanagari, etc.) */
+    writingSystem: string;
+    /** Text direction */
+    direction: 'ltr' | 'rtl';
+    /** Recommended font families */
+    fontFamily: string;
+    /** Fallback fonts */
+    fallbackFonts: string[];
+    /** Whether language uses formal/informal forms */
+    formalForms: boolean;
+    /** Whether language uses honorifics */
+    honorifics: boolean;
+}
+interface TranslationEntry {
+    /** Unique key for this translation */
+    key: string;
+    /** Source language code */
+    sourceLanguage: string;
+    /** Target language code */
+    targetLanguage: string;
+    /** Original text */
+    sourceText: string;
+    /** Translated text */
+    targetText: string;
+    /** Context for translation (formal, informal, technical, etc.) */
+    context: string;
+    /** Category (ui, compliance, legal, etc.) */
+    category: string;
+    /** Cultural notes for translators */
+    culturalNotes: string;
+    /** Whether translation has been verified */
+    verified: boolean;
+    /** Who verified this translation */
+    verifiedBy?: string;
+    /** Quality score (0-1) */
+    qualityScore: number;
+    /** Last update timestamp */
+    lastUpdated: string;
+}
+interface CulturalContextConfig {
+    /** Country code (ISO 3166-1 alpha-2) */
+    countryCode: string;
+    /** Core cultural values */
+    culturalValues: string[];
+    /** Communication style preferences */
+    communicationStyle: 'formal' | 'informal' | 'community-oriented' | 'hierarchical';
+    /** Decision-making patterns */
+    decisionMaking: 'individual' | 'consensus' | 'elder-consultation' | 'community';
+    /** Conflict resolution approach */
+    conflictResolution: string;
+    /** Traditional knowledge to integrate */
+    traditionalKnowledge: string[];
+    /** Local examples to use in explanations */
+    localExamples: string[];
+    /** Topics to avoid */
+    taboos: string[];
+    /** Local celebrations to acknowledge */
+    celebrations: string[];
+    /** Community structure description */
+    communityStructure: string;
+}
+interface I18nOptions {
+    /** Country code for cultural context */
+    country: string;
+    /** Primary language code */
+    primaryLanguage: string;
+    /** Additional local language codes */
+    localLanguages?: string[];
+    /** Fallback language if translation not found */
+    fallbackLanguage: string;
+    /** Enable offline translation caching */
+    offlineEnabled?: boolean;
+    /** Custom translations to merge */
+    customTranslations?: Record<string, TranslationEntry>;
+}
+interface TranslateOptions {
+    /** Target language (defaults to primaryLanguage) */
+    lang?: string;
+    /** Context for translation */
+    context?: 'formal' | 'informal' | 'technical' | 'legal';
+    /** Specific dialect */
+    dialect?: string;
+    /** Interpolation values */
+    values?: Record<string, string | number>;
+    /** Plural count for pluralization */
+    count?: number;
+}
+interface DetectionResult {
+    /** Detected language code */
+    language: string;
+    /** Confidence score (0-1) */
+    confidence: number;
+    /** Possible alternatives */
+    alternatives: Array<{
+        language: string;
+        confidence: number;
+    }>;
+}
+
+/**
+ * Cultural Context Management
+ * Provides cultural adaptation beyond translation
+ */
+
+/**
+ * Get cultural context for a country
+ */
+declare function getCulturalContext(countryCode: string): CulturalContextConfig | null;
+/**
+ * Cultural context class with helper methods
+ */
+declare class CulturalContext {
+    private config;
+    constructor(countryCode: string);
+    /**
+     * Check if formal communication style is expected
+     */
+    get usesFormalAddress(): boolean;
+    /**
+     * Check if community consultation is expected for decisions
+     */
+    get requiresCommunityConsultation(): boolean;
+    /**
+     * Get local examples for explanations
+     */
+    getLocalExamples(): string[];
+    /**
+     * Check if a topic should be avoided
+     */
+    isTaboo(topic: string): boolean;
+    /**
+     * Get traditional knowledge integration points
+     */
+    getTraditionalKnowledge(): string[];
+    /**
+     * Get raw config
+     */
+    toJSON(): CulturalContextConfig;
+}
+
+/**
+ * Translation engine with fallback chain.
+ *
+ * Supports interpolation (`{name}`), pluralization, and a locale
+ * fallback chain: exact locale → base language → fallback language.
+ */
+
+type TranslationMap = Record<string, string | Record<string, string>>;
+type TranslationCatalog = Record<string, TranslationMap>;
+interface TranslatorOptions {
+    /** Primary locale (e.g. 'tw', 'sw', 'en') */
+    locale: string;
+    /** Fallback locale when a key is missing. Defaults to `'en'`. */
+    fallbackLocale?: string;
+    /** Translation dictionaries keyed by locale. */
+    catalog: TranslationCatalog;
+}
+/**
+ * Lightweight translation function factory.
+ *
+ * ```ts
+ * const { t } = createTranslator({
+ *   locale: 'tw',
+ *   catalog: {
+ *     en: { greeting: 'Hello, {name}!' },
+ *     tw: { greeting: 'Akwaaba, {name}!' },
+ *   },
+ * });
+ * t('greeting', { values: { name: 'Kofi' } }); // → 'Akwaaba, Kofi!'
+ * ```
+ */
+declare function createTranslator(options: TranslatorOptions): {
+    t: (key: string, opts?: TranslateOptions) => string;
+    locale: string;
+    fallbackLocale: string;
+};
+
+/**
+ * Locale-aware formatters using the native `Intl` APIs.
+ *
+ * These wrappers exist so that GTCX apps don't import `Intl` directly
+ * and can be tested/mocked uniformly.
+ */
+/** Format a number according to locale conventions. */
+declare function formatNumber(value: number, locale: string, options?: Intl.NumberFormatOptions): string;
+/** Format a currency value. */
+declare function formatCurrency(value: number, locale: string, currency: string, options?: Omit<Intl.NumberFormatOptions, 'style' | 'currency'>): string;
+/** Format a date. */
+declare function formatI18nDate(date: Date | string, locale: string, options?: Intl.DateTimeFormatOptions): string;
+/** Format a relative time (e.g. "3 days ago"). */
+declare function formatRelativeTime(value: number, unit: Intl.RelativeTimeFormatUnit, locale: string): string;
+
+/**
+ * RTL (Right-to-Left) detection utilities.
+ */
+/** Returns `true` if the given locale code uses a right-to-left script. */
+declare function isRTL(locale: string): boolean;
+/** Returns `'rtl'` or `'ltr'` for use in HTML `dir` attributes. */
+declare function getDirection(locale: string): 'rtl' | 'ltr';
+
+/**
+ * Supported languages and language families
+ */
+declare const SUPPORTED_LANGUAGES: {
+    readonly en: {
+        readonly name: "English";
+        readonly nativeName: "English";
+        readonly direction: "ltr";
+    };
+    readonly fr: {
+        readonly name: "French";
+        readonly nativeName: "Français";
+        readonly direction: "ltr";
+    };
+    readonly es: {
+        readonly name: "Spanish";
+        readonly nativeName: "Español";
+        readonly direction: "ltr";
+    };
+    readonly pt: {
+        readonly name: "Portuguese";
+        readonly nativeName: "Português";
+        readonly direction: "ltr";
+    };
+    readonly ar: {
+        readonly name: "Arabic";
+        readonly nativeName: "العربية";
+        readonly direction: "rtl";
+    };
+    readonly zh: {
+        readonly name: "Chinese";
+        readonly nativeName: "中文";
+        readonly direction: "ltr";
+    };
+    readonly hi: {
+        readonly name: "Hindi";
+        readonly nativeName: "हिन्दी";
+        readonly direction: "ltr";
+    };
+    readonly tw: {
+        readonly name: "Twi";
+        readonly nativeName: "Twi";
+        readonly direction: "ltr";
+    };
+    readonly gaa: {
+        readonly name: "Ga";
+        readonly nativeName: "Gã";
+        readonly direction: "ltr";
+    };
+    readonly ee: {
+        readonly name: "Ewe";
+        readonly nativeName: "Eʋegbe";
+        readonly direction: "ltr";
+    };
+    readonly dag: {
+        readonly name: "Dagbani";
+        readonly nativeName: "Dagbanli";
+        readonly direction: "ltr";
+    };
+    readonly yo: {
+        readonly name: "Yoruba";
+        readonly nativeName: "Yorùbá";
+        readonly direction: "ltr";
+    };
+    readonly ig: {
+        readonly name: "Igbo";
+        readonly nativeName: "Igbo";
+        readonly direction: "ltr";
+    };
+    readonly ha: {
+        readonly name: "Hausa";
+        readonly nativeName: "Hausa";
+        readonly direction: "ltr";
+    };
+    readonly wo: {
+        readonly name: "Wolof";
+        readonly nativeName: "Wolof";
+        readonly direction: "ltr";
+    };
+    readonly sw: {
+        readonly name: "Swahili";
+        readonly nativeName: "Kiswahili";
+        readonly direction: "ltr";
+    };
+    readonly ki: {
+        readonly name: "Kikuyu";
+        readonly nativeName: "Gĩkũyũ";
+        readonly direction: "ltr";
+    };
+    readonly luo: {
+        readonly name: "Luo";
+        readonly nativeName: "Dholuo";
+        readonly direction: "ltr";
+    };
+    readonly kam: {
+        readonly name: "Kamba";
+        readonly nativeName: "Kikamba";
+        readonly direction: "ltr";
+    };
+    readonly kln: {
+        readonly name: "Kalenjin";
+        readonly nativeName: "Kalenjin";
+        readonly direction: "ltr";
+    };
+    readonly suk: {
+        readonly name: "Sukuma";
+        readonly nativeName: "Kisukuma";
+        readonly direction: "ltr";
+    };
+    readonly hay: {
+        readonly name: "Haya";
+        readonly nativeName: "Kihaya";
+        readonly direction: "ltr";
+    };
+    readonly qu: {
+        readonly name: "Quechua";
+        readonly nativeName: "Runasimi";
+        readonly direction: "ltr";
+    };
+    readonly ay: {
+        readonly name: "Aymara";
+        readonly nativeName: "Aymar aru";
+        readonly direction: "ltr";
+    };
+    readonly gn: {
+        readonly name: "Guarani";
+        readonly nativeName: "Avañe'ẽ";
+        readonly direction: "ltr";
+    };
+    readonly bn: {
+        readonly name: "Bengali";
+        readonly nativeName: "বাংলা";
+        readonly direction: "ltr";
+    };
+    readonly ta: {
+        readonly name: "Tamil";
+        readonly nativeName: "தமிழ்";
+        readonly direction: "ltr";
+    };
+    readonly te: {
+        readonly name: "Telugu";
+        readonly nativeName: "తెలుగు";
+        readonly direction: "ltr";
+    };
+    readonly mr: {
+        readonly name: "Marathi";
+        readonly nativeName: "मराठी";
+        readonly direction: "ltr";
+    };
+};
+declare const LANGUAGE_FAMILIES: {
+    readonly niger_congo: readonly ["tw", "gaa", "ee", "dag", "yo", "ig", "sw", "ki", "luo", "suk"];
+    readonly afroasiatic: readonly ["ha", "ar"];
+    readonly indo_european: readonly ["en", "fr", "es", "pt", "hi", "bn", "mr"];
+    readonly quechuan: readonly ["qu"];
+    readonly aymaran: readonly ["ay"];
+    readonly sino_tibetan: readonly ["zh"];
+    readonly dravidian: readonly ["ta", "te"];
+    readonly tupian: readonly ["gn"];
+};
+
+export { CulturalContext, type CulturalContextConfig, type DetectionResult, type I18nOptions, LANGUAGE_FAMILIES, type LanguageConfig, SUPPORTED_LANGUAGES, type TranslateOptions, type TranslationCatalog, type TranslationEntry, type TranslationMap, type TranslatorOptions, createTranslator, formatCurrency, formatI18nDate, formatNumber, formatRelativeTime, getCulturalContext, getDirection, isRTL };