xcstrings-cli 2.5.1 → 2.7.0

package/README.md

@@ -9,18 +9,20 @@ We also provide a Custom GPT that can help you generate translations and output
 ## Installation
 
 1. Install xcstrings-cli using npm:
+
     ```bash
     npm install -g xcstrings-cli
     ```
 
     This will install the `xcs` command globally.
 
-2. Create a configuration file for your project by running:
+2. Create a [configuration file](#configuration-file) for your project by running:
+
     ```bash
     xcs init
     ```
 
-    This will ask you some questions and create an `xcstrings-cli.json` file in the current directory.
+    This will ask you some questions and create an `xcstrings-cli.yaml` file in the current directory.
 
 ## Usage
 
@@ -28,7 +30,7 @@ We also provide a Custom GPT that can help you generate translations and output
 
 ```bash
 # Add with key, comment, and default language string
-xcs add --key greeting --comment "A greeting message." --string "Hello, World."
+xcs add --key greeting --comment "A greeting message." --text "Hello, World."
 
 # Add with key, comment, and translations YAML via heredoc
 xcs add \
@@ -52,6 +54,9 @@ xcs add \
 }
 EOF
 
+# Start interactive mode to add translations using `$EDITOR` environment variable (e.g. `vim`)
+xcs add -i
+
 # Add translations via file
 xcs add \
     --key greeting \
@@ -99,7 +104,7 @@ xcs remove --languages ja zh-Hans
 
 **List supported languages:**
 
-If `xcodeprojPaths` is configured, this command lists languages from your Xcode project (knownRegions) and excludes `Base`. If `xcodeprojPaths` is not configured, it lists languages observed in the xcstrings file.
+If `xcodeprojPaths` is configured, this command lists languages from your Xcode project (knownRegions) and excludes `Base`. Otherwise, it lists languages appeared in the xcstrings file.
 
 ```bash
 xcs languages
@@ -149,94 +154,136 @@ xcs strings --format "[{{language}}] {{key}} => {{text}}"
 # ... etc.
 ```
 
+**Export strings to _xcstrings_ or traditional _strings_ files:**
+
+```bash
+# Export all strings to Test.xcstrings
+xcs export Test.xcstrings
+
+# Export keys starting with 'good' to Output.strings in language specific lproj folders
+xcs export --key good* --output strings Output
+```
+
 You can use `xcs --help` or `xcs <sub-command> --help` to see the list of commands and options.
 
 ## Commands
 
-### Global options
+**Global options:**
 
-* `--help, -h`: `boolean` (Optional)
-    * Show help.
-* `--version, -v`: `boolean` (Optional)
-    * Show version.
-* `--config`: `string` (Optional)
-    * The custom config file path. If not specified, `xcs` will look for `xcstrings-cli.json` or `xcstrings-cli.json5` in the current folder or its parent folders until the root.
-* `--path`: `string` (Optional)
-    * The xcstrings file path. Defaults to `Localizable.xcstrings` in the current directory, or to the first `xcstringsPaths` entry in the config when present.
-    * You can also specify the alias you set in the config file. (`xcstringsPaths` entry with `alias` field)
+- `--config`: `string` (Optional)
+    - The custom config file path. If not specified, `xcs` will look for `xcstrings-cli.json` or `xcstrings-cli.json5` in the current folder or its parent folders until the root.
+- `--help, -h`: `boolean` (Optional)
+    - Show help.
+- `--path`: `string` (Optional)
+    - The xcstrings file path. Defaults to `Localizable.xcstrings` in the current directory, or to the first `xcstringsPaths` entry in the config when present.
+    - You can also specify the alias you set in the config file. (`xcstringsPaths` entry with `alias` field)
+- `--version, -v`: `boolean` (Optional)
+    - Show version.
 
 ### `add` command
 
 Adds/updates one or more strings to the xcstrings file.
 
-* `--key, -k`: `string` (Required unless `--strings` contains one or more keys)
-    * The key of the string to add.
-* `--language, -l`: `string` (Optional)
-    * The language of the string provided with `--text`.
-    * Ignored if `--text` is not provided.
-    * If not specified, it uses the source language defined as `sourceLanguage` in the xcstrings file.
-    * Validation follows `missingLanguagePolicy`: `skip` requires the language to be supported; `include` allows any language.
-* `--text`: `string` (Optional)
-    * The string value for the language. If omitted, the key is created without a localization for the default language.
-* `--state`: `string` (Optional, default: `translated`)
-    * Values applied to single-key and multi-key adds: `translated`, `needs_review`, `new`, `stale`. If omitted, strings default to `translated`.
-    * Multi-key payloads can also set per-language states with `{ state, value }`; string shorthand is treated as `translated`.
-    * State meanings:
-        * `translated`: The string is translated and ready to use.
-        * `needs_review`: The string needs review by a translator.
-        * `new`: The string is newly added and not yet translated.
-        * `stale`: The string is outdated and may need re-translation.
-* `--strings`: `string` (Optional)
-    * Translation-including JSON or YAML for the key. Pass inline JSON, or provide the flag without a value to read it from stdin (heredoc/pipe).
-    * The format is determined by `--strings-format`.
-* `--strings-format`: `string` (Optional, default: `auto`)
-    * The format of the data provided with `--strings`. Options are:
-        * `auto`: Auto-detect format based on content.
-        * `yaml`: YAML format. (It uses `js-yaml` internally.)
-        * `json`: JSON format. (It uses `json5` internally.)
-* `--comment`: `string` (Optional)
-    * The comment for the string to add, intended for translators.
+**`add` command options:**
+
+- `--comment`: `string` (Optional)
+    - The comment for the string to add, intended for translators.
+- `--interactive, -i`: `boolean` (Optional)
+    - Start interactive mode to add strings.
+    - This is useful when you don't want to record a huge command to your terminal history.
+- `--key, -k`: `string` (Required unless `--strings` contains one or more keys)
+    - The key of the string to add.
+- `--language, -l`: `string` (Optional)
+    - The language of the string provided with `--text`.
+    - Ignored if `--text` is not provided.
+    - If not specified, it uses the source language defined as `sourceLanguage` in the xcstrings file.
+    - Validation follows `missingLanguagePolicy`: `skip` requires the language to be supported; `include` allows any language.
+- `--state`: `string` (Optional, default: `translated`)
+    - Values applied to single-key and multi-key adds: `translated`, `needs_review`, `new`, `stale`. If omitted, strings default to `translated`.
+    - Multi-key payloads can also set per-language states with `{ state, value }`; string shorthand is treated as `translated`.
+    - Available states: `translated`, `needs_review`, `new`, `stale`
+- `--strings`: `string` (Optional)
+    - Translation-including JSON or YAML for the key. Pass inline JSON, or provide the flag without a value to read it from stdin (heredoc/pipe).
+    - The format is determined by `--strings-format`.
+- `--strings-format`: `string` (Optional, default: `auto`)
+    - The format of the data provided with `--strings`. Options are:
+        - `auto`: Auto-detect format based on content.
+        - `yaml`: YAML format.
+        - `json`: JSON format. JSON5 is also supported.
+- `--text`: `string` (Optional)
+    - The string value for the language. If omitted, the key is created without a localization for the default language.
 
 ### `remove` command
 
 Removes strings from the xcstrings file based on the specified filter options.
 
-* `--key, -k`: `string` (Optional if `languages` is specified)
-    * The key of the string to remove. If not specified, xcstrings-cli will remove all strings for the specified languages.
-* `--languages, -l`: `string[]` (Optional if `key` is specified)
-    * The languages to remove. If not specified, `xcs` will remove the string for all languages.
-* `--dry-run, -n`: `boolean` (Optional, default: `false`)
-    * If set to `true`, `xcs` will only show what would be removed without actually removing anything.
+**`remove` command options:**
+
+- `--dry-run, -n`: `boolean` (Optional, default: `false`)
+    - If set to `true`, `xcs` will only show what would be removed without actually removing anything.
+- `--key, -k`: `string` (Optional if `languages` is specified)
+    - The key of the string to remove. If not specified, xcstrings-cli will remove all strings for the specified languages.
+- `--languages, -l`: `string[]` (Optional if `key` is specified)
+    - The languages to remove. If not specified, `xcs` will remove the string for all languages.
 
 ### `strings` command
 
 Lists strings in the xcstrings file, with optional filtering and formatting.
 
-* `--languages, -l`: `string[]` (Optional)
-    * Include only the specified languages.
-* `--key`, `--key-glob`: `string` (Optional)
-    * Filter keys by glob pattern. This is the default key filter mode.
-* `--key-regex`: `string` (Optional)
-    * Filter keys by regular expression.
-* `--key-substring`: `string` (Optional)
-    * Filter keys by substring match.
-* `--text`, `--text-glob`: `string` (Optional)
-    * Filter translations by glob pattern. This is the default text filter mode.
-* `--text-regex`: `string` (Optional)
-    * Filter translations by regular expression.
-* `--text-substring`: `string` (Optional)
-    * Filter translations by substring match.
-* `--format`: `string` (Optional)
-    * Mustache template for per-localization output. Available variables: `{{language}}`, `{{key}}`, `{{text}}`.
-
-## Config file
-
-Put an `xcstrings-cli.json5` or `xcstrings-cli.json` file in the project root, and xcs will use it as the config file.
+**`strings` commands options:**
+
+- `--format`: `string` (Optional)
+    - Mustache template for per-localization output. Available variables: `{{language}}`, `{{key}}`, `{{text}}`.
+- `--key`, `--key-glob`: `string` (Optional)
+    - Filter keys by glob pattern. This is the default key filter mode.
+- `--key-regex`: `string` (Optional)
+    - Filter keys by regular expression.
+- `--key-substring`: `string` (Optional)
+    - Filter keys by substring match.
+- `--languages, -l`: `string[]` (Optional)
+    - Include only the specified languages.
+- `--text`, `--text-glob`: `string` (Optional)
+    - Filter translations by glob pattern. This is the default text filter mode.
+- `--text-regex`: `string` (Optional)
+    - Filter translations by regular expression.
+- `--text-substring`: `string` (Optional)
+    - Filter translations by substring match.
+
+### `export` command
+
+Exports xcstrings to either filtered xcstrings or traditional `.strings` format.
+
+**`export` command options:**
+
+- `--output, -o`: `string` (Optional, default: `auto`)
+    - The output format. Options are:
+        - `auto`: Inferred from the output path extension if possible.
+        - `xcstrings`: Export to a `.xcstrings` catalog format.
+        - `strings`: Export to Apple's traditional `.strings` format generated in `<language>.lproj` directories.
+- `--merge-policy, -m`: `string` (Optional, default: `error`)
+    - How to handle existing translation files:
+        - `error`: Stop safely if an output file exists.
+        - `force`: Clobber and overwrite existing files.
+        - `output-first`: Augment existing files, preferring new translations over old ones.
+        - `existing-first`: Keep existing translations intact, appending only non-overlapping strings.
+- Filtering options from the `strings` command are also supported:
+    - `--key`, `--key-glob`, `--key-regex`, `--key-substring`
+    - `--text`, `--text-glob`, `--text-regex`, `--text-substring`
+    - `--languages, -l`
+
+## Configuration file
+
+Put a config file named `xcstrings-cli` in the project root, using one of the following extensions:
+
+- `.json`: JSON format
+- `.json5`: JSON5 format
+- `.yml` `.yaml`: YAML format
 
 Here is an example config file in JSON format:
 
 ```json
 {
+    "missingLanguagePolicy": "include",
     "xcstringsPaths": [
         "Shared/L10n/Localizable.xcstrings",
         {
@@ -244,27 +291,24 @@ Here is an example config file in JSON format:
             "path": "packages/Utils/Sources/Utils/Resources/Localizable.xcstrings"
         }
     ],
-    "xcodeprojPaths": [
-        "path/to/your/Project.xcodeproj"
-    ],
-    "missingLanguagePolicy": "include"
+    "xcodeprojPaths": ["path/to/your/Project.xcodeproj"]
 }
 ```
 
 These are the settings you can specify in the config file:
 
-* **xcstringsPaths**: `string[] | { alias: string, path: string }[]` (Optional)
-    * Paths to xcstrings files used by `xcs`.
-    * If only one path is provided, `xcs` will use it as the default xcstrings file.
-    * If multiple paths are provided, `xcs` will ask you to select an xcstrings file.
-    * You can also specify an alias, and use it with the `--path` option.
-* **xcodeprojPaths**: `string[]` (Optional)
-    * Paths to Xcode project files (`.xcodeproj`) used to detect supported languages.
-    * If not specified, `xcs` will only check the xcstrings file to detect supported languages.
-* **missingLanguagePolicy**: `string` (Optional, default: `skip`)
-    * How to handle translations for languages that are not included in the `xcs languages` output when adding strings. Options are:
-    * `skip`: Only add translations for languages included in the `xcs languages` output. (Default)
-    * `include`: Add translations even when they are not recognized by the Xcode project or xcs language list.
+- **missingLanguagePolicy**: `string` (Optional, default: `skip`)
+    - How to handle translations for languages that are not included in the `xcs languages` output when adding strings. Options are:
+    - `skip`: Only add translations for languages included in the `xcs languages` output. (Default)
+    - `include`: Add translations even when they are not recognized by the Xcode project or xcs language list.
+- **xcodeprojPaths**: `string[]` (Optional)
+    - Paths to Xcode project files (`.xcodeproj`) used to detect supported languages.
+    - If not specified, `xcs` will only check the xcstrings file to detect supported languages.
+- **xcstringsPaths**: `(string | { alias: string; path: string })[]` (Optional)
+    - Paths to xcstrings files used by `xcs`.
+    - If only one path is provided, `xcs` will use it as the default xcstrings file.
+    - If multiple paths are provided, `xcs` will ask you to select an xcstrings file.
+    - You can also specify an alias, and use it with the `--path` option.
 
 ## Practical use cases
 
@@ -294,10 +338,9 @@ Languages: ja, zh-Hans
 No comments needed.
 ```
 
-Then the Custom GPT will generate an `xcs add` command like this:
+Then the Custom GPT will generate YAML like this:
 
-```bash
-xcs add --strings << EOF
+```yaml
 closeAction:
     translations:
         en: Close
@@ -308,10 +351,9 @@ detailsAction:
         en: Details
         ja: 詳細
         zh-Hans: 详情
-EOF
 ```
 
-Finally, copy the generated command and run it in your terminal to add the translations to your xcstrings file.
+Finally, copy the generated YAML and run `xcs add -i` to add the translations to your xcstrings file via interactive mode.
 
 ## Q&A