1.2.0 (#55)

- Xcode localization file support — Added parsers for .strings, .stringsdict, and .xcstrings formats
- Locked keys & exclude integration tests — Added test coverage for lockedKeys and exclude features
- Plain text (.txt) file support — New parser for .txt files
- Direct file and text translation — Ability to translate files or raw text directly, without requiring a
full project config
- Selective key translation (includeKeys) — Filter which keys get translated

Author: Starllordz

.gitignore

@@ -26,4 +26,5 @@ coverage/
 # tmp files
 tmp/
 
-.claude/
+.claude/
+CLAUDE.md

README.md

@@ -4,9 +4,9 @@
 
 Lara Cli automates translation of your i18n files with a single command, preserving structure and formatting while integrating with a professional translation API. Given a source language, it translates your content to selected target languages based on your source i18n files.
 
-Supports multiple file formats including JSON, PO (gettext), TypeScript, Vue I18n single-file components, Markdown and MDX files, and Android XML string resource files. See [Supported Formats](docs/config/formats.md) for details.
+Supports multiple file formats including JSON, PO (gettext), TypeScript, Vue I18n single-file components, Markdown and MDX files, Android XML string resource files, Xcode localization files (.strings, .stringsdict, .xcstrings), and plain text (.txt) files. See [Supported Formats](docs/config/formats.md) for details.
 
-[![Version](https://img.shields.io/badge/version-1.1.0-blue.svg)](https://github.com/translated/lara-cli)
+[![Version](https://img.shields.io/badge/version-1.2.0-blue.svg)](https://github.com/translated/lara-cli)
 
 </div>
 
@@ -236,4 +236,8 @@ For detailed documentation on using Lara CLI:
 - [PO Files Guide](docs/config/files/po-files.md) - Complete guide for gettext PO files
 - [Vue Files Guide](docs/config/files/vue-files.md) - Complete guide for Vue I18n single-file components
 - [Markdown Files Guide](docs/config/files/md-files.md) - Complete guide for Markdown and MDX files
-- [Android XML Files Guide](docs/config/files/android-xml-files.md) - Complete guide for Android XML string resource files
+- [Android XML Files Guide](docs/config/files/android-xml-files.md) - Complete guide for Android XML string resource files
+- [Xcode Strings Files Guide](docs/config/files/xcode-strings-files.md) - Complete guide for Xcode .strings files
+- [Xcode Stringsdict Files Guide](docs/config/files/xcode-stringsdict-files.md) - Complete guide for Xcode .stringsdict plural files
+- [Xcode String Catalogs Guide](docs/config/files/xcode-xcstrings-files.md) - Complete guide for Xcode .xcstrings String Catalogs
+- [TXT Files Guide](docs/config/files/txt-files.md) - Complete guide for plain text files

docs/README.md

@@ -14,6 +14,15 @@ To get started with Lara CLI, follow these steps:
 2. **Initialize your project**: Run `lara-cli init` to create a configuration file
 3. **Translate your files**: Run `lara-cli translate` to process translations
 
+For quick, one-off translations or CI/CD pipelines, you can also use **direct translation** without any configuration:
+
+```bash
+lara-cli translate --text "Hello, world!" --source en --target fr
+lara-cli translate --file "messages.json" --source en --target fr --output "messages-fr.json"
+```
+
+See the [Translate Command](commands/translate.md) documentation for details.
+
 ## Command Reference
 
 Lara CLI provides several commands to manage your internationalization:
@@ -43,3 +52,7 @@ The `lara.yaml` configuration file controls how Lara CLI works with your project
 - [Vue Files Guide](config/files/vue-files.md) - Complete guide for Vue I18n single-file components
 - [Markdown Files Guide](config/files/md-files.md) - Complete guide for Markdown and MDX files
 - [Android XML Files Guide](config/files/android-xml-files.md) - Complete guide for Android XML string resource files
+- [Xcode Strings Files Guide](config/files/xcode-strings-files.md) - Complete guide for Xcode .strings files
+- [Xcode Stringsdict Files Guide](config/files/xcode-stringsdict-files.md) - Complete guide for Xcode .stringsdict plural files
+- [Xcode String Catalogs Guide](config/files/xcode-xcstrings-files.md) - Complete guide for Xcode .xcstrings String Catalogs
+- [TXT Files Guide](config/files/txt-files.md) - Complete guide for plain text files

docs/commands/translate.md

@@ -129,6 +129,86 @@ Use `--force` when you need to:
 - Fix translation errors by regenerating all translations
 - Reset translations after configuration changes
 
+## Direct Translation
+
+In addition to config-based translation, the `translate` command supports direct file and text translation. This mode is designed for CI/CD pipelines, scripting, and one-off translations — no `lara.yaml` configuration file is needed.
+
+### Direct Text Translation
+
+Translate a text string directly:
+
+```bash
+lara-cli translate --text "Hello, world!" --source en-US --target fr-FR
+```
+
+The translated text is printed to stdout, making it easy to pipe into other commands:
+
+```bash
+lara-cli translate --text "Welcome" --source en --target es | pbcopy
+```
+
+### Direct File Translation
+
+Translate a file directly:
+
+```bash
+lara-cli translate --file "/path/to/file.txt" --source en-US --target fr-FR
+```
+
+By default, the translated content is printed to stdout. Use `--output` to write to a file:
+
+```bash
+lara-cli translate --file "messages.json" --source en --target fr --output "messages-fr.json"
+```
+
+#### Structured vs Plain Text Files
+
+Only [supported file formats](../config/formats.md) are accepted (JSON, PO, XML, Markdown, TXT, etc.). Each format is parsed and translated preserving file structure, formatting, and non-string values. For `.txt` files, each non-empty line is translated independently while empty lines are preserved. Unsupported file types (e.g., `.png`, `.csv`) are rejected with an error.
+
+### Direct Translation Options
+
+| Option | Description |
+|--------|-------------|
+| `--file <path>` | Path to a file to translate directly |
+| `--text <string>` | Text string to translate directly |
+| `-s, --source <locale>` | Source locale (required with `--file` or `--text`) |
+| `-o, --output <path>` | Output file path (only with `--file`) |
+| `-m, --translation-memories <ids>` | Translation Memory IDs (comma-separated) |
+| `-g, --glossaries <ids>` | Glossary IDs (comma-separated) |
+
+### Using Translation Memories & Glossaries
+
+You can use Translation Memories and Glossaries in direct mode by passing their IDs:
+
+```bash
+lara-cli translate --text "Hello" --source en --target fr -m "mem_abc123"
+lara-cli translate --file "messages.json" --source en --target fr -m "mem_abc,mem_def" -g "gls_xyz"
+```
+
+Use `lara-cli memory` and `lara-cli glossary` to list available IDs.
+
+### Differences from Config-Based Mode
+
+| Feature | Config Mode | Direct Mode |
+|---------|-------------|-------------|
+| Requires `lara.yaml` | Yes | No |
+| Change detection (checksums) | Yes | No |
+| Locked/ignored keys | Yes | No |
+| Translation instructions | Yes | No |
+| Multiple target locales per invocation | Yes | No (one at a time) |
+| Translation Memories & Glossaries | Yes | Yes |
+
+### Prerequisites
+
+Direct translation only requires API credentials. No `lara-cli init` is needed:
+
+```
+LARA_ACCESS_KEY_ID=your_access_key_id
+LARA_ACCESS_KEY_SECRET=your_access_key_secret
+```
+
+Set these as environment variables or in a `.env` file in your working directory.
+
 ## Related
 
 - [Configuration Reference](../config/README.md) - Detailed configuration options

docs/config/files.md

@@ -24,6 +24,9 @@ files:
       - "config/*/url"
     ignoredKeys:
       - "internal/**"
+    includeKeys:
+      - "ui/**"
+      - "messages/**"
 ```
 
 ## Properties
@@ -56,7 +59,14 @@ files:
 - **Description**: Identifies keys that should be left untouched in target files (not translated, not added, not removed)
 - **Format**: Uses glob patterns for matching keys (e.g., `internal/**`, `**/debug`)
 
-## Locked vs Ignored Keys
+### includeKeys
+
+- **Type**: Array of strings (key patterns)
+- **Required**: No (defaults to empty array)
+- **Description**: When specified, only keys matching these patterns will be translated. All other keys are treated as ignored (preserved in existing target files, not added to new ones). When empty (default), all keys are included.
+- **Format**: Uses glob patterns for matching keys (e.g., `ui/**`, `messages/*`)
+
+## Locked vs Ignored vs Include Keys
 
 Understanding the difference between `lockedKeys` and `ignoredKeys`:
 
@@ -156,6 +166,57 @@ Target file (`es.json`) - if `debug` already existed:
 
 Note: The `debug` key is never translated or modified by Lara. If it already exists in the target, it is preserved as-is. If it does not exist, it is not added.
 
+### Include Keys
+
+Keys listed in `includeKeys` define a whitelist: only matching keys are translated. All non-matching keys behave as if they were ignored. When `includeKeys` is empty (the default), all keys are in scope.
+
+Use this for:
+
+- Translating only a specific subset of a large file
+- Gradually rolling out translations for new keys
+- Focusing translation on specific namespaces
+
+**Example:**
+
+Source file (`en.json`):
+
+```json
+{
+  "ui": {
+    "title": "My Application",
+    "subtitle": "Welcome"
+  },
+  "internal": {
+    "debug": "Debug mode",
+    "version": "1.0.0"
+  }
+}
+```
+
+Configuration:
+
+```yaml
+includeKeys:
+  - "ui/**"
+```
+
+Target file (`es.json`):
+
+```json
+{
+  "ui": {
+    "title": "Mi Aplicación",
+    "subtitle": "Bienvenido"
+  }
+}
+```
+
+Note: Only `ui/**` keys are translated. The `internal` keys are not added to the target file. If they already existed in the target, they would be preserved as-is.
+
+**Interaction with `lockedKeys` and `ignoredKeys`:**
+
+`includeKeys` is evaluated first. Among included keys, `lockedKeys` and `ignoredKeys` still apply normally. Non-included keys are always treated as ignored, regardless of other settings.
+
 ## Path Patterns
 
 Paths in the `include` and `exclude` arrays must use the `[locale]` placeholder to indicate where locale codes should appear.
@@ -196,6 +257,7 @@ files:
     exclude: []
     lockedKeys: []
     ignoredKeys: []
+    includeKeys: []
 ```
 
 ### Complex Configuration
@@ -216,4 +278,7 @@ files:
     ignoredKeys:
       - "internal/**"
       - "**/debug"
+    includeKeys:
+      - "ui/**"
+      - "messages/**"
 ```