localingos 0.1.21 → 0.1.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "localingos",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "CLI tool to sync translations with Localingos",
   "main": "src/index.js",
   "type": "module",

package/src/commands/extract.js

@@ -197,6 +197,10 @@ export function generateExtractPrompt(config) {
     const outputPattern = config.outputPattern || '{locale}.json';
     const languageName = getLanguageName(sourceLocale);
 
+    const descriptionsFile = config.sourceFile
+        ? config.sourceFile.replace(/\.json$/, '.descriptions.json')
+        : `./src/i18n/${sourceLocale}.descriptions.json`;
+
     const formatExample = format === 'json-flat' 
         ? `{
   "page_name.section.element": "Source text in ${languageName} here"
@@ -209,6 +213,18 @@ export function generateExtractPrompt(config) {
   }
 }`;
 
+    const descriptionsExample = format === 'json-flat'
+        ? `{
+  "page_name.section.element": "Context for translators — where this text appears and what it means"
+}`
+        : `{
+  "page_name": {
+    "section": {
+      "element": "Context for translators — where this text appears and what it means"
+    }
+  }
+}`;
+
     // ─── Build framework-aware i18n setup instructions ───────────────────
     let i18nSetupInstructions;
     if (i18nLib) {
@@ -289,11 +305,21 @@ export const HeroMessages = defineMessages({
     text: 'Get Started',
     description: 'Primary CTA button in the hero section',
   },
+  GREETING: {
+    id: 'homepage.hero.greeting',
+    text: 'Hello, {{name}}!',
+    description: 'Personalized greeting — {{name}} is a placeholder',
+  },
 });
 \`\`\`
 
 **Rules for \`*${msgExt}\` files:**
-- Each entry has \`id\` (dot-separated key), \`text\` (the ${languageName} source text), and optional \`description\`
+- Each entry has \`id\` (dot-separated key), \`text\` (the ${languageName} source text), and **required** \`description\`
+- The \`description\` field is critical for translation quality — it tells the AI translator the context. Include:
+  - Where the text appears (e.g. "Header on the billing page", "Placeholder in the search input")
+  - What surrounds it (e.g. "Shown when user has no active subscription", "Button below the pricing cards")
+  - What any variables represent (e.g. "{{days}} is the number of trial days remaining")
+  - Any technical terms that need context (e.g. "CLI refers to the command-line interface tool")
 - Use UPPER_SNAKE_CASE for the Record keys (e.g. \`TITLE\`, \`BTN_SUBMIT\`, \`ERROR_REQUIRED\`)
 - The \`id\` must be unique across the entire project — no two entries in any \`*${msgExt}\` file can share the same \`id\`
 - Group keys by \`{page}.{section}.{element}\` using lowercase_snake_case
@@ -320,11 +346,29 @@ import { HeroMessages } from './Hero.messages';
 ### Step 4: Create the extraction script
 
 Create \`scripts/extract-messages.js\` — a deterministic Node.js script that:
-1. Finds all \`**/*${msgExt}\` files in the source directory
-2. Parses each file to extract \`id\` and \`text\` from every \`MessageDefinition\`
-3. Builds nested JSON from all dot-path ids, using \`text\` as the ${languageName} value
-4. Merges into the existing \`${sourceFile}\` — **never overwrites existing values**, only adds new keys
-5. Reports: new keys added, existing keys preserved, duplicate ids (which should error and abort)
+1. Reads the source locale and output paths from \`.localingos.json\` (fields: \`sourceLocale\`, \`sourceFile\`, \`outputDir\`). Fall back to \`sourceLocale: "${sourceLocale}"\`, \`sourceFile: "${sourceFile}"\`, \`outputDir: "${outputDir}"\` if the config file or fields are missing.
+2. Finds all \`**/*${msgExt}\` files in the source directory
+3. Parses each file to extract \`id\`, \`text\`, and \`description\` from every \`MessageDefinition\`
+4. Builds nested JSON from all dot-path ids, using \`text\` as the ${languageName} value, and writes it to the configured \`sourceFile\` path
+5. Builds a **separate descriptions file** at the same path but with a \`.descriptions.json\` suffix (e.g. \`${descriptionsFile}\`) using the same nested structure, but with \`description\` as the value. Only include keys that have a non-empty \`description\`. If no descriptions exist at all, still write an empty \`{}\` file.
+6. Merges into the existing source file — **never overwrites existing values**, only adds new keys
+7. Reports: new keys added, existing keys preserved, duplicate ids (which should error and abort)
+
+**IMPORTANT**: Do NOT hardcode the output file name (e.g. \`en-US.json\`). The script must derive it from the \`sourceFile\` field in \`.localingos.json\` so it works for any configured locale.
+
+The descriptions file uses the **same key structure** as the source file, but values are the description strings instead of the source text:
+
+Source file (\`${sourceFile}\`):
+\`\`\`json
+${formatExample}
+\`\`\`
+
+Descriptions file (\`${descriptionsFile}\`):
+\`\`\`json
+${descriptionsExample}
+\`\`\`
+
+The descriptions file is consumed by \`localingos sync\` to provide context to the AI translator. It is NOT loaded by the i18n runtime — it is only used during the sync/push step. The i18n library only reads the source file and translation files.
 
 Wire it as an npm script:
 \`\`\`json
@@ -336,13 +380,14 @@ Wire it as an npm script:
 \`\`\`
 
 The script must:
-- Parse \`*${msgExt}\` files using regex (not TypeScript compilation) — look for \`id:\` and \`text:\` string literals within each \`{ ... }\` block
+- Parse \`*${msgExt}\` files using regex (not TypeScript compilation) — look for \`id:\`, \`text:\`, and \`description:\` string literals within each \`{ ... }\` block
 - Support single-quoted, double-quoted, and backtick string literals
 - Convert dot-separated ids to nested JSON: \`'homepage.hero.title'\` → \`{ homepage: { hero: { title: "..." } } }\`
+- Write the source text to \`${sourceFile}\` and descriptions to \`${descriptionsFile}\` (both using the same nested key structure)
 - Error on duplicate ids across different files
-- With \`--prune\` flag: also remove keys from the JSON that no longer exist in any \`*${msgExt}\` file
+- With \`--prune\` flag: also remove keys from both JSON files that no longer exist in any \`*${msgExt}\` file
 - When NOT using \`--prune\`, if stale keys are detected, print: \`Run "npm run i18n:extract -- --prune" to remove them\`
-- With \`--check\` flag: exit with error code if the JSON would change (for CI use)
+- With \`--check\` flag: exit with error code if either JSON file would change (for CI use)
 
 ---
 
@@ -361,16 +406,16 @@ ${i18nSetupInstructions}`;
 ${i18nSetupInstructions}
 ${i18nLib ? `3` : `2`}. Replace **every** hardcoded user-facing string in the source code with the appropriate i18n translation function call (e.g., \`t('key')\`, \`$t('key')\`, \`intl.formatMessage()\`, \`AppLocalizations.of(context).key\`, or whatever is idiomatic for the framework)
 ${i18nLib ? `4` : `3`}. Make sure the i18n import/hook/injection is added to every file that uses translation calls
-${i18nLib ? `5` : `4`}. Preserve any dynamic values using interpolation: \`t('greeting', { name: userName })\``;
+${i18nLib ? `5` : `4`}. Preserve any dynamic values using interpolation: `t('greeting', { name: userName })` with `{{name}}` in the translation string`;
     }
 
     // ─── Assemble the full prompt ────────────────────────────────────────
     const prompt = `## Task: Internationalize this project — extract all translatable strings and wire up i18n end-to-end
 
 Scan this codebase and perform a **complete internationalization (i18n) setup**. This means:
-1. Extract every user-facing string into structured message definition files
+1. Extract every user-facing string into structured message definition files (with descriptions for translator context)
 2. Replace every hardcoded string in the source code with a translation function call referencing the message definition
-3. Create a deterministic extraction script that builds the source locale JSON from the message files
+3. Create a deterministic extraction script that builds the source locale JSON and a descriptions sidecar JSON from the message files
 4. Set up the i18n framework so the app loads translations at runtime
 
 The source language for this project is **${languageName}** (\`${sourceLocale}\`). All extracted strings must be in ${languageName}.
@@ -416,18 +461,25 @@ ${messageDefinitionSection}${nonJsI18nInstructions}
 ---
 
 ### Critical requirements:
-- **Extract ALL user-facing strings** — do not leave any hardcoded text in the source code
+- **Work file by file** — iterate through each component file one at a time. For each file:
+  1. Scan for ALL hardcoded strings: JSX text content AND string attributes (\`placeholder=\`, \`label=\`, \`header=\`, \`description=\`, \`loadingText=\`, \`emptyText=\`, \`errorText=\`, \`constraintText=\`, \`title=\`, \`ariaLabel=\`, \`alt=\`)
+  2. Create or update the co-located \`*${msgExt}\` file with all extracted strings, each with a meaningful \`description\`
+  3. Update the component to use \`t()\` calls for every extracted string
+  4. Move to the next file
+- **Extract ALL user-facing strings** — do not leave any hardcoded text in the source code. Check both JSX children AND component props/attributes
 - **Replace ALL hardcoded strings** with translation function calls — the app must render text from the i18n source file, not from inline strings${isJsProject ? `
 - **Never use raw string keys** — always reference through the Messages object: \`t(ComponentMessages.KEY)\`, not \`t('raw.key')\`` : ''}${isJsProject ? `
 - **Every component with translatable text must have a co-located \`*${msgExt}\` file**` : ''}
-- If a string contains dynamic values like \`\${name}\` or \`{count}\`, use the i18n library's interpolation syntax: \`"Hello, {name}"\` in the source file, \`t('key', { name })\` in the code
+- **Every message MUST have a \`description\` field** — this is not optional. The description provides context for AI translators and directly impacts translation quality. A missing description means a worse translation.
+- If a string contains dynamic values like \`\${name}\` or \`{count}\`, use **double-brace** interpolation syntax: \`"Hello, {{name}}"\` in the source file, \`t('key', { name })\` in the code. CRITICAL: i18next requires \`{{double braces}}\` in translation strings — single \`{braces}\` will NOT interpolate.
 - Maintain the original text exactly as-is in the source file (in ${languageName})${isJsProject ? `
-- After creating all message files, run the extraction script to generate \`${sourceFile}\` from the message definitions` : ''}
+- After creating all message files, run the extraction script to generate \`${sourceFile}\` and \`${descriptionsFile}\` from the message definitions` : ''}
 - After this is done, running \`localingos sync\` will push the source strings to Localingos and pull back translations for other languages — the app should already be wired to load those translated files from \`${outputDir}/\`
 - **Add a language/locale selector** to the app UI in the most appropriate, visible location (e.g., navigation bar, header, settings page, or footer). The selector must:
   - Display the available locales based on the translation files present in \`${outputDir}/\`
   - Allow users to switch languages at runtime
   - Persist the user's language preference (e.g., localStorage)
+  - On first visit (no saved preference), auto-detect the user's locale from \`navigator.language\`. If it matches a supported locale, use it. If only the base language matches (e.g. browser is "de" and you support "de-DE"), use the closest match. Otherwise fall back to \`${sourceLocale}\`.
   - Use the project's i18n framework to change the active locale (e.g., \`i18n.changeLanguage(locale)\` for i18next)
   - Show locale names in their native language when possible (e.g., "Español" not "Spanish", "Deutsch" not "German")
   - If a locale selector component already exists in the project, update it rather than creating a duplicate`;
@@ -465,7 +517,7 @@ ${messageDefinitionSection}${nonJsI18nInstructions}
     }
 
     if (isJsProject) {
-        console.log(chalk.blue(`\nAfter the AI has created all *${msgExt} files and the extraction script, run "npm run i18n:extract" to generate ${sourceFile}, then "localingos sync" to push and get translations.\n`));
+        console.log(chalk.blue(`\nAfter the AI has created all *${msgExt} files and the extraction script, run "npm run i18n:extract" to generate ${sourceFile} and the descriptions file, then "localingos sync" to push and get translations.\n`));
     } else {
         console.log(chalk.blue(`\nAfter the AI has internationalized your code, run "localingos sync" to push source strings and get translations.\n`));
     }

package/src/formats/json-flat.js

@@ -4,9 +4,20 @@ import path from 'path';
 export function extract(filePath) {
     const raw = fs.readFileSync(filePath, 'utf-8');
     const json = JSON.parse(raw);
+
+    // Load descriptions sidecar file if it exists
+    const descPath = filePath.replace(/\.json$/, '.descriptions.json');
+    let descriptions = {};
+    if (fs.existsSync(descPath)) {
+        try {
+            descriptions = JSON.parse(fs.readFileSync(descPath, 'utf-8'));
+        } catch (e) { /* ignore malformed descriptions file */ }
+    }
+
     return Object.entries(json).map(([key, value]) => ({
         id: key,
-        text: String(value)
+        text: String(value),
+        ...(descriptions[key] ? { description: String(descriptions[key]) } : {})
     }));
 }
 

package/src/formats/json-nested.js

@@ -41,7 +41,24 @@ function unflatten(translations) {
 export function extract(filePath) {
     const raw = fs.readFileSync(filePath, 'utf-8');
     const json = JSON.parse(raw);
-    return flatten(json);
+    const entries = flatten(json);
+
+    // Load descriptions sidecar file if it exists
+    const descPath = filePath.replace(/\.json$/, '.descriptions.json');
+    let descriptions = {};
+    if (fs.existsSync(descPath)) {
+        try {
+            const descEntries = flatten(JSON.parse(fs.readFileSync(descPath, 'utf-8')));
+            for (const d of descEntries) {
+                descriptions[d.id] = d.text;
+            }
+        } catch (e) { /* ignore malformed descriptions file */ }
+    }
+
+    return entries.map(e => ({
+        ...e,
+        ...(descriptions[e.id] ? { description: descriptions[e.id] } : {})
+    }));
 }
 
 export function write(translations, outputDir, outputPattern) {