@djangocfg/i18n 2.1.162 → 2.1.164

package/README.md

@@ -1,14 +1,14 @@
 # @djangocfg/i18n
 
-Lightweight, type-safe i18n library for @djangocfg component packages. Provides built-in translations for English, Russian, and Korean with easy extensibility.
+Lightweight, type-safe i18n library with LLM-powered translation CLI.
 
 ## Features
 
-- **Type-safe** - Full TypeScript support with autocomplete for translation keys
-- **Lightweight** - No heavy dependencies, pure React
-- **Extensible** - Easy to add custom translations or override defaults
-- **Works standalone** - Components work without provider using English defaults
-- **3 languages built-in** - English, Russian, Korean
+- **17 languages** - en, ru, ko, ja, de, fr, zh, it, es, nl, ar, tr, pt-BR, pl, sv, no, da
+- **LLM Translation** - Translate with GPT-4o-mini via CLI
+- **Type-safe** - Full TypeScript support with autocomplete
+- **CLI included** - Manage and translate locales
+- **Works standalone** - Components work without provider
 
 ## Installation
 
@@ -21,29 +21,111 @@ pnpm add @djangocfg/i18n
 ```tsx
 import { I18nProvider, useT, ru } from '@djangocfg/i18n'
 
-// Wrap your app (optional - works without provider too)
+// Wrap your app
 <I18nProvider locale="ru" translations={ru}>
   <App />
 </I18nProvider>
 
-// Use in components - simplest way
+// Use in components
 function MyComponent() {
   const t = useT()
   return <span>{t('ui.form.save')}</span>
 }
 ```
 
+## CLI
+
+Built-in CLI with LLM translation support.
+
+### Translate Text
+
+```bash
+# Translate to multiple languages
+pnpm i18n translate "Hello World" --to ru,ko,ja
+# => ru: Привет, мир
+# => ko: 안녕하세요, 세계
+# => ja: こんにちは、世界
+
+# Output as JSON
+pnpm i18n translate "Save" --to ru,ko --json
+# => {"en":"Save","ru":"Сохранить","ko":"저장"}
+```
+
+### Translate Locale File
+
+```bash
+# Translate entire en.ts to Russian
+pnpm i18n translate ru
+
+# Or explicit
+pnpm i18n translate --file --to ru --from en
+```
+
+### Sync Missing Keys
+
+```bash
+# Show missing keys
+pnpm i18n sync --dry
+
+# Add with [TODO] placeholders
+pnpm i18n sync
+
+# Sync with LLM translation
+pnpm i18n sync --translate
+
+# Sync specific locales
+pnpm i18n sync --to ru,ko --translate
+```
+
+### Other Commands
+
+```bash
+# List/search keys
+pnpm i18n list              # All keys
+pnpm i18n list tour         # Search pattern
+pnpm i18n list -v           # With values
+
+# Check missing keys
+pnpm i18n check
+
+# Add key to all locales
+pnpm i18n add "tools.new" '{"en":"New","ru":"Новый"}'
+
+# Show translation cache stats
+pnpm i18n translate --stats
+```
+
+### Working with App Locales
+
+CLI supports any locales directory (.ts or .json files):
+
+```bash
+# Hub app
+pnpm i18n translate "Dashboard" --to ru,ko -d ../../apps/hub/i18n/locales
+
+# Sync with LLM translation
+pnpm i18n sync -d ../../apps/hub/i18n/locales --translate
+```
+
+### Environment Variables
+
+```bash
+# Optional - uses built-in test key by default
+SDKROUTER_API_KEY=your-key   # SDKRouter (recommended)
+OPENAI_API_KEY=your-key      # OpenAI
+ANTHROPIC_API_KEY=your-key   # Anthropic
+```
+
 ## Hooks
 
 | Hook | Description |
 |------|-------------|
-| `useT()` | Returns translation function, works with/without provider (recommended) |
+| `useT()` | Returns translation function (recommended) |
 | `useI18n()` | Full context: `{ t, locale, setLocale, translations }` |
-| `useTranslation()` | Alias for `useT()` |
 | `useLocale()` | Returns current locale string |
-| `useTypedT<T>()` | Type-safe translation function with compile-time key validation |
+| `useTypedT<T>()` | Type-safe with compile-time key validation |
 
-### useT() - Recommended
+### useT()
 
 ```tsx
 function MyComponent() {
@@ -52,7 +134,7 @@ function MyComponent() {
 }
 ```
 
-### useI18n() - Full Context
+### useI18n()
 
 ```tsx
 function LocaleSwitcher() {
@@ -62,13 +144,12 @@ function LocaleSwitcher() {
     <select value={locale} onChange={(e) => setLocale(e.target.value)}>
       <option value="en">English</option>
       <option value="ru">Russian</option>
-      <option value="ko">Korean</option>
     </select>
   )
 }
 ```
 
-### useTypedT<T>() - Type-Safe Keys
+### useTypedT<T>()
 
 ```tsx
 import { useTypedT } from '@djangocfg/i18n'
@@ -81,69 +162,25 @@ function MyComponent() {
 }
 ```
 
-### getT() - Non-Hook Context
-
-For class components or outside React:
-
-```tsx
-import { getT } from '@djangocfg/i18n'
-
-const label = getT('ui.form.save')
-const message = getT('ui.pagination.showing', { from: 1, to: 10, total: 100 })
-```
-
 ## Extending Translations
 
 ### mergeTranslations()
 
-Deep merge base translations with custom overrides. Supports generic type parameter for app-specific namespaces:
-
 ```tsx
 import { mergeTranslations, ru } from '@djangocfg/i18n'
 
-// Override specific keys
 const customRu = mergeTranslations(ru, {
-  ui: {
-    select: { placeholder: 'Выберите марку авто...' }
-  }
+  ui: { select: { placeholder: 'Выберите...' } },
+  app: { title: 'Мое приложение' }
 })
-
-// Add app-specific namespace with type safety
-type AppNamespace = { app: { title: string; welcome: string } }
-
-const appRu = mergeTranslations<AppNamespace>(ru, {
-  app: {
-    title: 'Мое приложение',
-    welcome: 'Добро пожаловать!'
-  }
-})
-// Result type: I18nTranslations & AppNamespace
-```
-
-### createTranslations()
-
-Create translations from multiple partial sources:
-
-```tsx
-import { createTranslations, en } from '@djangocfg/i18n'
-
-const translations = createTranslations(
-  en,              // base
-  uiOverrides,     // UI customizations
-  appStrings       // App-specific strings
-)
 ```
 
 ## Built-in Locales
 
 ```tsx
-import { en, ru, ko } from '@djangocfg/i18n'
+import { en, ru, ko, ja, de, fr, zh, it, es, nl, ar, tr, ptBR, pl, sv, no, da } from '@djangocfg/i18n'
 ```
 
-- `en` - English (default)
-- `ru` - Russian
-- `ko` - Korean
-
 ## Interpolation
 
 ```tsx
@@ -154,81 +191,19 @@ t('ui.select.moreItems', { count: 5 })
 // => "+5 more"
 ```
 
-## Type Utilities
-
-```tsx
-import type { PathKeys, I18nKeys, I18nTranslations } from '@djangocfg/i18n'
-
-// Get all valid keys from any translations type
-type MyKeys = PathKeys<MyTranslations>
-// = "form.title" | "form.submit" | "messages.error" | ...
-
-// Built-in keys for base translations
-const key: I18nKeys = 'ui.form.save'  // OK
-const bad: I18nKeys = 'ui.form.typo'  // Error
-```
-
 ## Translation Key Paths
 
-All translation keys use dot notation:
-
-### UI Components
-
-```
-ui.select.placeholder      - "Select option..."
-ui.select.search           - "Search..."
-ui.select.noResults        - "No results found."
-ui.select.selectAll        - "Select all"
-ui.select.clearAll         - "Clear all"
-ui.select.moreItems        - "+{count} more"
-
-ui.pagination.previous     - "Previous"
-ui.pagination.next         - "Next"
-ui.pagination.showing      - "{from}-{to} of {total}"
-
-ui.form.submit             - "Submit"
-ui.form.save               - "Save"
-ui.form.cancel             - "Cancel"
-ui.form.delete             - "Delete"
-ui.form.loading            - "Loading..."
-ui.form.required           - "This field is required"
-
-ui.dialog.close            - "Close"
-ui.dialog.confirm          - "Confirm"
-
-ui.errors.generic          - "Something went wrong"
-ui.errors.network          - "Network error..."
 ```
-
-### Layouts
-
-```
-layouts.sidebar.toggle     - "Toggle sidebar"
-layouts.profile.settings   - "Settings"
-layouts.profile.logout     - "Log out"
-layouts.theme.light        - "Light"
-layouts.theme.dark         - "Dark"
-```
-
-### API
-
-```
-api.errors.networkError    - "Network error"
-api.status.connecting      - "Connecting..."
-api.status.connected       - "Connected"
+ui.*         - UI components (select, form, dialog, table, pagination)
+layouts.*    - Layout components (sidebar, auth, profile, theme)
+api.*        - API/network messages
+centrifugo.* - WebSocket monitoring
+tools.*      - Heavy tools (tour, upload, code, image)
 ```
 
 ## Works Without Provider
 
-Components using `useT()` or `useI18n()` work without provider - they fall back to English defaults. This allows gradual adoption in existing projects.
-
-## Integration with @djangocfg packages
-
-This package is designed to work with:
-- `@djangocfg/ui-core` - Base React components
-- `@djangocfg/ui-nextjs` - Next.js specific components
-- `@djangocfg/layouts` - Layout components
-- `@djangocfg/nextjs` - Next.js App Router integration with next-intl
+Components using `useT()` work without provider - they fall back to English defaults.
 
 ## License
 

package/dist/cli/index.d.mts

@@ -0,0 +1 @@
+#!/usr/bin/env node