Skip to content

Commit 13c2845

Browse files
StarllordzStarllordz
committed
feat: add Xcode localization file support
## Changed - Parser factory uses getFileType() for extension-to-type mapping - Config validation supports [locale].lproj/ path patterns - Init command groups Xcode files under xcode-* config keys - searchPaths() uses actual file extensions for disk globbing ## New - .strings parser (regex-based key-value parsing with comment preservation) - .stringsdict parser (XML plist plural rules via fast-xml-parser) - .xcstrings parser (JSON String Catalogs with multi-locale support) - FILE_EXTENSION_TO_TYPE_MAP for strings/stringsdict/xcstrings mapping - getFileType() utility for config-level type resolution - .lproj directory normalization in path utilities - 107 new tests (unit + integration) for all three formats - Format-specific documentation guides for each Xcode file type
1 parent e73c936 commit 13c2845

23 files changed

Lines changed: 5321 additions & 27 deletions

‎README.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
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.
66

7-
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.
7+
Supports multiple file formats including JSON, PO (gettext), TypeScript, Vue I18n single-file components, Markdown and MDX files, Android XML string resource files, and Xcode localization files (.strings, .stringsdict, .xcstrings). See [Supported Formats](docs/config/formats.md) for details.
88

99
[![Version](https://img.shields.io/badge/version-1.1.0-blue.svg)](https://github.com/translated/lara-cli)
1010

@@ -236,4 +236,7 @@ For detailed documentation on using Lara CLI:
236236
- [PO Files Guide](docs/config/files/po-files.md) - Complete guide for gettext PO files
237237
- [Vue Files Guide](docs/config/files/vue-files.md) - Complete guide for Vue I18n single-file components
238238
- [Markdown Files Guide](docs/config/files/md-files.md) - Complete guide for Markdown and MDX files
239-
- [Android XML Files Guide](docs/config/files/android-xml-files.md) - Complete guide for Android XML string resource files
239+
- [Android XML Files Guide](docs/config/files/android-xml-files.md) - Complete guide for Android XML string resource files
240+
- [Xcode Strings Files Guide](docs/config/files/xcode-strings-files.md) - Complete guide for Xcode .strings files
241+
- [Xcode Stringsdict Files Guide](docs/config/files/xcode-stringsdict-files.md) - Complete guide for Xcode .stringsdict plural files
242+
- [Xcode String Catalogs Guide](docs/config/files/xcode-xcstrings-files.md) - Complete guide for Xcode .xcstrings String Catalogs

‎docs/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,3 +43,6 @@ The `lara.yaml` configuration file controls how Lara CLI works with your project
4343
- [Vue Files Guide](config/files/vue-files.md) - Complete guide for Vue I18n single-file components
4444
- [Markdown Files Guide](config/files/md-files.md) - Complete guide for Markdown and MDX files
4545
- [Android XML Files Guide](config/files/android-xml-files.md) - Complete guide for Android XML string resource files
46+
- [Xcode Strings Files Guide](config/files/xcode-strings-files.md) - Complete guide for Xcode .strings files
47+
- [Xcode Stringsdict Files Guide](config/files/xcode-stringsdict-files.md) - Complete guide for Xcode .stringsdict plural files
48+
- [Xcode String Catalogs Guide](config/files/xcode-xcstrings-files.md) - Complete guide for Xcode .xcstrings String Catalogs

‎docs/config/files/xcode-strings-files.md‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
# Xcode .strings Files Configuration
2+
3+
This guide explains how to use Lara CLI with Xcode `.strings` localization files, commonly used in iOS and macOS applications.
4+
5+
## What are .strings Files?
6+
7+
Xcode `.strings` files are the traditional format for storing localized strings in Apple applications. They use a simple key-value pair format organized by locale in `.lproj` directories (e.g., `en.lproj/Localizable.strings`, `fr.lproj/Localizable.strings`).
8+
9+
Lara CLI supports `.strings` files with:
10+
11+
- Simple key-value string pairs
12+
- C-style comments (`/* ... */`)
13+
- Escape sequences (`\"`, `\\`, `\n`, `\t`, `\U` unicode)
14+
15+
## Configuration
16+
17+
To configure Xcode `.strings` files in your `lara.yaml`:
18+
19+
```yaml
20+
files:
21+
xcode-strings:
22+
include:
23+
- "[locale].lproj/Localizable.strings"
24+
exclude: []
25+
lockedKeys: []
26+
ignoredKeys: []
27+
```
28+
29+
> **Note:** The configuration key is `xcode-strings` (not `strings`). Lara CLI automatically maps `.strings` file extensions to this config key.
30+
>
31+
> **Important:** Lara CLI uses `[locale].lproj/Localizable.strings` structure (e.g., `en.lproj/Localizable.strings`, `fr.lproj/Localizable.strings`). The `[locale]` placeholder is replaced with the locale code.
32+
33+
### File Path Patterns
34+
35+
#### Standard Structure (Recommended)
36+
37+
```yaml
38+
files:
39+
xcode-strings:
40+
include:
41+
- "[locale].lproj/Localizable.strings"
42+
- "[locale].lproj/InfoPlist.strings"
43+
```
44+
45+
This follows the structure:
46+
47+
```text
48+
MyApp/
49+
en.lproj/
50+
Localizable.strings
51+
InfoPlist.strings
52+
fr.lproj/
53+
Localizable.strings
54+
InfoPlist.strings
55+
es.lproj/
56+
Localizable.strings
57+
InfoPlist.strings
58+
```
59+
60+
#### Custom Structure
61+
62+
```yaml
63+
files:
64+
xcode-strings:
65+
include:
66+
- "Resources/[locale].lproj/Localizable.strings"
67+
```
68+
69+
## .strings File Format
70+
71+
### Basic Format
72+
73+
```
74+
/* App Name */
75+
"app_name" = "My App";
76+
77+
/* Greeting message */
78+
"hello" = "Hello World";
79+
80+
/* Button labels */
81+
"button_submit" = "Submit";
82+
"button_cancel" = "Cancel";
83+
```
84+
85+
Each entry follows the format: `"key" = "value";`
86+
87+
### Comments
88+
89+
C-style block comments and single-line comments are supported and preserved during translation:
90+
91+
```
92+
/* Section: Login Screen */
93+
"login_title" = "Welcome Back";
94+
95+
// Username field placeholder
96+
"login_username" = "Enter your username";
97+
```
98+
99+
### Escape Sequences
100+
101+
```
102+
"escaped_quotes" = "Say \"Hello\"";
103+
"newline" = "Line 1\nLine 2";
104+
"tab" = "Column 1\tColumn 2";
105+
"backslash" = "C:\\Users\\file";
106+
"unicode" = "\U00E9";
107+
```
108+
109+
### Empty Values
110+
111+
```
112+
"empty_key" = "";
113+
```
114+
115+
## How Lara CLI Handles .strings Files
116+
117+
### Automatic Processing
118+
119+
Lara CLI automatically:
120+
121+
- Extracts key-value pairs from `.strings` files
122+
- Preserves comments and their association with keys
123+
- Maintains key ordering from the source file
124+
- Handles escape sequences correctly
125+
- Preserves file formatting
126+
127+
### Key Path Format
128+
129+
When using `lockedKeys` or `ignoredKeys`, use the key name directly:
130+
131+
```yaml
132+
files:
133+
xcode-strings:
134+
include:
135+
- "[locale].lproj/Localizable.strings"
136+
lockedKeys:
137+
- "app_name" # Exact key
138+
- "api_*" # Wildcard pattern
139+
ignoredKeys:
140+
- "debug_*" # Ignore all debug keys
141+
```
142+
143+
## Complete Example
144+
145+
```yaml
146+
version: "1.0.0"
147+
148+
project:
149+
instruction: "iOS app, user-friendly tone"
150+
151+
locales:
152+
source: en
153+
target:
154+
- es
155+
- fr
156+
- de
157+
158+
files:
159+
xcode-strings:
160+
include:
161+
- "[locale].lproj/Localizable.strings"
162+
- "[locale].lproj/InfoPlist.strings"
163+
exclude: []
164+
lockedKeys:
165+
- "app_name"
166+
ignoredKeys:
167+
- "debug_*"
168+
fileInstructions:
169+
- path: "[locale].lproj/Localizable.strings"
170+
instruction: "User-facing messages, friendly tone"
171+
```
172+
173+
## Working with Existing .strings Files
174+
175+
1. **Run `lara-cli init`** to create your configuration
176+
2. **Ensure your file paths match the `include` patterns**
177+
3. **Run `lara-cli translate`**
178+
4. **Continue developing** - Lara CLI tracks changes via checksums
179+
180+
If your `.strings` files don't exist yet:
181+
182+
1. **Create your source locale file** (e.g., `en.lproj/Localizable.strings`)
183+
2. **Run `lara-cli translate`** - target locale files are created automatically
184+
185+
## Limitations
186+
187+
- Must use `"key" = "value";` format
188+
- Keys and values must be double-quoted
189+
- Each entry must end with a semicolon
190+
- Files must be organized by locale in `.lproj` directories
191+
192+
## Troubleshooting
193+
194+
### Keys Not Found
195+
196+
- Ensure entries follow the `"key" = "value";` format
197+
- Check that semicolons are present at the end of each entry
198+
- Verify the file encoding is UTF-8
199+
200+
### Comments Missing
201+
202+
- Lara CLI preserves block comments (`/* ... */`) and single-line comments (`// ...`)
203+
- Comments are associated with the entry that follows them
204+
205+
## Related Documentation
206+
207+
- [Supported Formats](../formats.md) - Overview of all supported file formats
208+
- [Files Configuration](../files.md) - General file configuration options
209+
- [Xcode Stringsdict Files](./xcode-stringsdict-files.md) - Plural support for Xcode
210+
- [Xcode String Catalogs](./xcode-xcstrings-files.md) - Modern Xcode 15+ format

0 commit comments

Comments
 (0)