chore: format

Author: davidturnbull

inject-locale.md

@@ -0,0 +1,374 @@
+# Inject locale
+
+## Introduction
+
+When your translation files include locale codes as data values, such as `"locale": "en"` or `"lang": "fr"`, these codes create two problems. First, they are redundant because the file's locale is already determined by its location or filename. Second, if sent to translation services, they could be mistranslated or increase translation costs unnecessarily.
+
+The inject locale feature solves both problems. It automatically removes locale codes before translation and re-inserts them afterward, ensuring the codes always match each file's actual locale without manual intervention.
+
+## What inject locale does
+
+Inject locale manages specific fields in your translation files that contain locale codes. You specify which fields to manage using key patterns, and Lingo handles the rest during the translation process.
+
+The feature operates in two phases. During the reading phase, Lingo identifies fields where the value matches the current locale and temporarily removes them. During the writing phase, Lingo re-inserts these fields with the appropriate locale code for each target language.
+
+## Supported bucket types
+
+Inject locale works with these bucket types:
+
+- json
+- json5
+- jsonc
+- json-dictionary
+
+Other bucket types do not support this feature.
+
+## Configuration
+
+Add the `injectLocale` option to your bucket configuration in `i18n.json`. The value is an array of key patterns that specify which fields contain locale codes.
+
+```json
+{
+  "version": 1.9,
+  "locale": {
+    "source": "en",
+    "targets": ["fr", "de", "es"]
+  },
+  "buckets": {
+    "json": {
+      "include": ["locales/[locale].json"],
+      "injectLocale": ["locale"]
+    }
+  }
+}
+```
+
+In this configuration, any field named `locale` that contains a locale code will be automatically managed.
+
+## Key patterns
+
+Key patterns specify which fields to manage. Patterns use dot notation for nested fields and support wildcards for flexible matching.
+
+### Simple patterns
+
+Simple patterns match specific fields by name.
+
+**Top-level field:**
+
+```json
+{
+  "injectLocale": ["locale"]
+}
+```
+
+This matches:
+
+```json
+{
+  "locale": "en"
+}
+```
+
+**Nested field:**
+
+```json
+{
+  "injectLocale": ["meta.locale"]
+}
+```
+
+This matches:
+
+```json
+{
+  "meta": {
+    "locale": "en"
+  }
+}
+```
+
+**Multiple fields:**
+
+```json
+{
+  "injectLocale": ["locale", "lang", "meta.language"]
+}
+```
+
+This matches any of these fields if their value is a locale code.
+
+### Wildcard patterns
+
+Wildcards match multiple fields with a single pattern. Use `*` to match any single path segment.
+
+**Single wildcard:**
+
+```json
+{
+  "injectLocale": ["pages.*.locale"]
+}
+```
+
+This matches:
+
+```json
+{
+  "pages": {
+    "home": { "locale": "en" },
+    "about": { "locale": "en" },
+    "contact": { "locale": "en" }
+  }
+}
+```
+
+**Multiple wildcards:**
+
+```json
+{
+  "injectLocale": ["sections.*.meta.locale"]
+}
+```
+
+This matches nested structures where locale codes appear at a consistent depth.
+
+### Forward slash notation
+
+Patterns support forward slashes for keys that contain slashes in their names.
+
+```json
+{
+  "injectLocale": ["meta/a/lang", "meta/b/lang"]
+}
+```
+
+This matches:
+
+```json
+{
+  "meta/a/lang": "en",
+  "meta/b/lang": "en"
+}
+```
+
+## How inject locale works
+
+Understanding the mechanism helps you predict behavior and troubleshoot issues.
+
+### Reading phase
+
+When Lingo reads a source file, it scans for fields matching your patterns. For each match, it checks whether the field's value equals the current locale code. If the value matches, Lingo removes the field temporarily. If the value does not match, Lingo leaves the field unchanged.
+
+**Example:**
+
+Source file `locales/en.json`:
+
+```json
+{
+  "locale": "en",
+  "welcome": "Welcome",
+  "meta": {
+    "locale": "en"
+  }
+}
+```
+
+Configuration:
+
+```json
+{
+  "injectLocale": ["locale", "meta.locale"]
+}
+```
+
+After reading, the internal representation excludes the locale fields:
+
+```json
+{
+  "welcome": "Welcome"
+}
+```
+
+The removed fields are recorded so they can be re-inserted later.
+
+### Writing phase
+
+When Lingo writes a translated file, it re-inserts the fields that were removed during reading. Each field receives the locale code appropriate for the target file.
+
+**Example:**
+
+After translating to French, Lingo writes `locales/fr.json`:
+
+```json
+{
+  "locale": "fr",
+  "welcome": "Bienvenue",
+  "meta": {
+    "locale": "fr"
+  }
+}
+```
+
+The locale fields now contain `"fr"` instead of `"en"`, matching the target locale.
+
+## Conditional behavior
+
+Inject locale only affects fields that meet specific conditions.
+
+**A field is removed during reading if:**
+
+1. The field matches a pattern in `injectLocale`
+2. The field's value exactly equals the current locale code
+
+**A field is re-inserted during writing if:**
+
+1. The field was removed during reading
+2. The field existed in the original source file
+
+This conditional behavior prevents unintended modifications. If a field's value is not a locale code, Lingo leaves it unchanged. If a field did not exist in the source, Lingo does not add it to translations.
+
+## Complete example
+
+This example demonstrates inject locale with a multi-page application structure.
+
+### Source file
+
+File: `locales/en.json`
+
+```json
+{
+  "locale": "en",
+  "pages": {
+    "home": {
+      "locale": "en",
+      "title": "Home",
+      "description": "Welcome to our website"
+    },
+    "about": {
+      "locale": "en",
+      "title": "About",
+      "description": "Learn more about us"
+    },
+    "contact": {
+      "locale": "fr",
+      "title": "Contact",
+      "description": "Get in touch"
+    }
+  }
+}
+```
+
+### Configuration
+
+```json
+{
+  "version": 1.9,
+  "locale": {
+    "source": "en",
+    "targets": ["fr", "de"]
+  },
+  "buckets": {
+    "json": {
+      "include": ["locales/[locale].json"],
+      "injectLocale": ["locale", "pages.*.locale"]
+    }
+  }
+}
+```
+
+### Translation result
+
+File: `locales/fr.json`
+
+```json
+{
+  "locale": "fr",
+  "pages": {
+    "home": {
+      "locale": "fr",
+      "title": "Accueil",
+      "description": "Bienvenue sur notre site"
+    },
+    "about": {
+      "locale": "fr",
+      "title": "À propos",
+      "description": "En savoir plus sur nous"
+    },
+    "contact": {
+      "locale": "fr",
+      "title": "Contact",
+      "description": "Contactez-nous"
+    }
+  }
+}
+```
+
+Notice that:
+
+- The top-level `locale` field changed from `"en"` to `"fr"`
+- The `pages.home.locale` field changed from `"en"` to `"fr"`
+- The `pages.about.locale` field changed from `"en"` to `"fr"`
+- The `pages.contact.locale` field remained `"fr"` because it did not match the source locale
+
+## Common patterns
+
+These patterns cover typical use cases.
+
+**Application metadata:**
+
+```json
+{
+  "injectLocale": ["locale", "lang", "language"]
+}
+```
+
+**CMS content:**
+
+```json
+{
+  "injectLocale": ["meta.locale", "content.lang"]
+}
+```
+
+**Multi-page structures:**
+
+```json
+{
+  "injectLocale": ["*.locale", "pages.*.meta.lang"]
+}
+```
+
+**Framework configurations:**
+
+```json
+{
+  "injectLocale": ["config.locale", "settings.language"]
+}
+```
+
+## Relationship to locked keys
+
+The `lockedKeys` feature serves a different purpose. Locked keys prevent specific fields from being translated at all. Inject locale, by contrast, removes fields temporarily but allows other fields in the same file to be translated.
+
+Use `lockedKeys` when a field should never change. Use `injectLocale` when a field should automatically update to match the target locale.
+
+## Troubleshooting
+
+**Locale fields are being translated:**
+
+Check that the field's value exactly matches the source locale code. Inject locale only removes fields when the value is a locale code. If the value is different, the field will be sent for translation.
+
+**Locale fields are not appearing in translations:**
+
+Verify that your patterns match the field paths in your files. Use dot notation for nested fields and ensure wildcard patterns align with your file structure.
+
+**Some locale fields update but others do not:**
+
+Inject locale only affects fields that matched the source locale during reading. If a field contained a different locale code in the source file, it will not be updated in translations.
+
+## Technical details
+
+Inject locale is implemented as a loader in the translation pipeline. The loader processes files at `src/cli/loaders/inject-locale.ts:6` and uses the minimatch library for pattern matching.
+
+During the pull operation, the loader calls `_getKeysWithLocales` at `src/cli/loaders/inject-locale.ts:14` to identify matching fields and removes them using lodash's `omit` function. During the push operation, the loader re-inserts the removed fields at `src/cli/loaders/inject-locale.ts:30` using lodash's `set` function with the target locale.
+
+The feature was introduced in configuration version 1.3 and enhanced in version 0.107.0 to support forward slash notation in patterns.