xcstrings-cli 2.0.0 → 2.2.0

package/README.md

@@ -15,7 +15,7 @@ We also provide a Custom GPT that can help you generate translations and output
 
     This will install the `xcs` command globally.
 
-2. Initialize xcstrings-cli:
+2. Create a configuration file for your project by running:
     ```bash
     xcs init
     ```
@@ -59,6 +59,21 @@ xcs add \
     --strings-format yaml \
     --strings < translations.yaml
 
+# Add multiple strings via heredoc
+xcs add --strings << EOF
+greeting:
+    translations:
+        en: Hello, World.
+        ja: こんにちは、世界。
+        zh-Hans: 你好，世界。
+    comment: A greeting message.
+farewell:
+    en: Goodbye, World.
+    ja: さようなら、世界。
+    zh-Hans: 再见，世界。
+    comment: A farewell message.
+EOF
+
 # Add with only key and comment
 xcs add --key greeting --comment "A greeting message."
 ```
@@ -84,6 +99,49 @@ xcs languages
 # en ja zh-Hans
 ```
 
+**List strings in the xcstrings file:**
+
+```bash
+# List all strings
+xcs list
+# helloWorld:
+#   en: "Hello, World."
+#   ja: "こんにちは、世界。"
+#   zh-Hans: "你好，世界。"
+# goodbyeWorld:
+#   en: "Goodbye, World."
+#   ja: "さようなら、世界。"
+# goodMorning:
+#   en: "Good morning."
+#   ja: "おはようございます。"
+# ... etc.
+
+# List strings filtered by key
+xcs list --key good*
+# goodbyeWorld:
+#   ...
+# goodMorning:
+#   ...
+
+# List strings filtered by language
+xcs list --languages en
+# helloWorld:
+#   en: "Hello, World."
+# goodbyeWorld:
+#   en: "Goodbye, World."
+# goodMorning:
+#   en: "Good morning."
+# ... etc.
+
+# List strings with custom format
+xcs list --format "[{{language}}] {{key}} => {{text}}"
+# [en] helloWorld => "Hello, World."
+# [ja] helloWorld => "こんにちは、世界。"
+# [en] goodbyeWorld => "Goodbye, World."
+# [ja] goodbyeWorld => "さようなら、世界。"
+# ... etc.
+```
+
 You can use `xcs --help` or `xcs <sub-command> --help` to see the list of commands and options.
 ## Command options
 
@@ -128,6 +186,25 @@ 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
+
+* `--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.
@@ -160,6 +237,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