xcstrings-cli 2.1.0 → 2.3.0

package/README.md

@@ -59,6 +59,28 @@ xcs add \
     --strings-format yaml \
     --strings < translations.yaml
 
+# Add multiple strings via heredoc (per-language objects support `state`; translated` by default)
+xcs add --strings << EOF
+greeting:
+    translations:
+        en: Hello, World.
+        ja:
+            state: needs_review
+            value: こんにちは、世界。
+        zh-Hans: 你好，世界。
+    comment: A greeting message.
+farewell:
+    translations:
+        en: Goodbye, World.
+        ja:
+            state: needs_review
+            value: さよなら、世界。
+        zh-Hans:
+            state: stale
+            value: さようなら、世界。
+    comment: A farewell message.
+EOF
+
 # Add with only key and comment
 xcs add --key greeting --comment "A greeting message."
 ```
@@ -142,7 +164,7 @@ You can use `xcs --help` or `xcs <sub-command> --help` to see the list of comman
 
 ### `add` command options
 
-* `--key, -k`: `string` (Required)
+* `--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`.
@@ -151,6 +173,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`.
@@ -222,6 +252,14 @@ These are the options for the config file:
     * `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.
 
+## Q&A
+
+**Q: Strings are not being added for some languages. Why?**
+
+A: By default, `xcs` only adds translations for languages that are recognized in your Xcode project (knownRegions) or the xcstrings file. You can check which languages are recognized by running `xcs languages`.
+
+If you want to add translations for languages not included in your Xcode project, you can change the `missingLanguagePolicy` in your config file to `include`.
+
 ## LICENSE
 
 MIT