xcstrings-cli 2.2.0 → 2.4.0

package/README.md

@@ -64,13 +64,20 @@ xcs add --strings << EOF
 greeting:
     translations:
         en: Hello, World.
-        ja: こんにちは、世界。
+        ja:
+            state: needs_review
+            value: こんにちは、世界。
         zh-Hans: 你好，世界。
     comment: A greeting message.
 farewell:
-    en: Goodbye, World.
-    ja: さようなら、世界。
-    zh-Hans: 再见，世界。
+    translations:
+        en: Goodbye, World.
+        ja:
+            state: needs_review
+            value: さよなら、世界。
+        zh-Hans:
+            state: stale
+            value: さようなら、世界。
     comment: A farewell message.
 EOF
 
@@ -103,7 +110,7 @@ xcs languages
 
 ```bash
 # List all strings
-xcs list
+xcs strings
 # helloWorld:
 #   en: "Hello, World."
 #   ja: "こんにちは、世界。"
@@ -117,14 +124,14 @@ xcs list
 # ... etc.
 
 # List strings filtered by key
-xcs list --key good*
+xcs strings --key good*
 # goodbyeWorld:
 #   ...
 # goodMorning:
 #   ...
 
 # List strings filtered by language
-xcs list --languages en
+xcs strings --languages en
 # helloWorld:
 #   en: "Hello, World."
 # goodbyeWorld:
@@ -134,7 +141,7 @@ xcs list --languages en
 # ... etc.
 
 # List strings with custom format
-xcs list --format "[{{language}}] {{key}} => {{text}}"
+xcs strings --format "[{{language}}] {{key}} => {{text}}"
 # [en] helloWorld => "Hello, World."
 # [ja] helloWorld => "こんにちは、世界。"
 # [en] goodbyeWorld => "Goodbye, World."
@@ -143,7 +150,10 @@ xcs list --format "[{{language}}] {{key}} => {{text}}"
 ```
 
 You can use `xcs --help` or `xcs <sub-command> --help` to see the list of commands and options.
-## Command options
+
+## Commands
+
+### Global options
 
 * `--help, -h`: `boolean` (Optional)
     * Show help.
@@ -155,9 +165,11 @@ You can use `xcs --help` or `xcs <sub-command> --help` to see the list of comman
     * 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)
 
-### `add` command options
+### `add` command
 
-* `--key, -k`: `string` (Required)
+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`.
@@ -166,6 +178,14 @@ You can use `xcs --help` or `xcs <sub-command> --help` to see the list of comman
     * 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`.
@@ -177,7 +197,9 @@ You can use `xcs --help` or `xcs <sub-command> --help` to see the list of comman
 * `--comment`: `string` (Optional)
     * The comment for the string to add, intended for translators.
 
-### `remove` command options
+### `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.
@@ -186,7 +208,9 @@ You can use `xcs --help` or `xcs <sub-command> --help` to see the list of comman
 * `--dry-run, -n`: `boolean` (Optional, default: `false`)
     * If set to `true`, `xcs` will only show what would be removed without actually removing anything.
 
-### `list` command options
+### `strings` command
+
+Lists strings in the xcstrings file, with optional filtering and formatting.
 
 * `--languages, -l`: `string[]` (Optional)
     * Include only the specified languages.
@@ -208,7 +232,10 @@ You can use `xcs --help` or `xcs <sub-command> --help` to see the list of comman
 ## 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.
-```json5
+
+Here is an example config file in JSON format:
+
+```json
 {
     "xcstringsPaths": [
         "Shared/L10n/Localizable.xcstrings",
@@ -219,19 +246,21 @@ Put an `xcstrings-cli.json5` or `xcstrings-cli.json` file in the project root, a
     ],
     "xcodeprojPaths": [
         "path/to/your/Project.xcodeproj"
-    ]
+    ],
+    "missingLanguagePolicy": "include"
 }
 ```
 
-These are the options for the config file:
+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.a
+    * 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 used to detect supported languages.
-    * If not specified, `xcs` will not check the supported languages in your Xcode project.
+    * 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)