xcstrings-cli 1.4.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +62 -32
  2. package/dist/index.js +1920 -485
  3. package/package.json +4 -1
package/README.md CHANGED
@@ -1,14 +1,12 @@
1
1
  # xcstrings-cli
2
2
 
3
- A command-line tool designed for working with **xcstrings** files.
3
+ [![Test](https://github.com/mshibanami/Docsloth/actions/workflows/test.yml/badge.svg)](https://github.com/mshibanami/Docsloth/actions/workflows/test.yml) [![npm version](https://badge.fury.io/js/xcstrings-cli.svg)](https://badge.fury.io/js/xcstrings-cli) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
4
4
 
5
- ## Guiding Principles
6
-
7
- This tool is built with the following goals in mind:
5
+ This is a command-line tool designed for working with **xcstrings** files, we follow these principles:
8
6
 
9
7
  - **Preserve Xcode’s formatting**: It avoids making unnecessary changes to `xcstrings` files generated by Xcode, including indentation, spacing, and ordering.
10
- - **No automatic translation**: It does not translate any content in your existing `xcstrings` files. The tool’s purpose is to help you manage and manipulate the files.
11
- - **AI-friendly workflow**: It is designed to make it easy to import translations generated by AI services now and in the future.
8
+ - **No automatic translation**: It does not translate any content in your existing `xcstrings` files.
9
+ - **AI-friendly workflow**: It makes it easy to import translations generated by AI services, such as ChatGPT, into your `xcstrings` files.
12
10
 
13
11
  ## AI Translation Support
14
12
 
@@ -34,16 +32,33 @@ This will ask you some questions and create an `xcstrings-cli.json` file in the
34
32
  **Add a string:**
35
33
 
36
34
  ```bash
35
+ # Add with key, comment, and default language string
36
+ xcstrings add --key greeting --comment "A greeting message." --string "Hello, World."
37
+
38
+ # Add with key, comment, and translations YAML via heredoc
39
+ xcstrings add \
40
+ --key greeting \
41
+ --comment "A greeting message." \
42
+ --strings << EOF
43
+ en: Hello, World.
44
+ ja: こんにちは、世界。
45
+ zh-Hans: 你好，世界。
46
+ EOF
47
+
48
+ # Or add translations JSON
37
49
  xcstrings add \
38
50
  --key greeting \
39
- --comment "Hello, World" \
51
+ --comment "A greeting message." \
40
52
  --strings << EOF
41
53
  {
42
- "ja": "こんにちは、世界。",
43
54
  "en": "Hello, World.",
55
+ "ja": "こんにちは、世界。",
44
56
  "zh-Hans": "你好，世界。"
45
57
  }
46
58
  EOF
59
+
60
+ # Add with only key and comment
61
+ xcstrings add --key greeting --comment "A greeting message."
47
62
  ```
48
63
 
49
64
  **Remove a string:**
@@ -60,7 +75,7 @@ xcstrings remove --languages ja zh-Hans
60
75
 
61
76
  **List supported languages:**
62
77
 
63
- This command lists all languages by checking xcstrings files and your Xcode project settings (`.pbxproj` specified in the config file as `xcodeprojPaths`).
78
+ 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.
64
79
 
65
80
  ```bash
66
81
  xcstrings languages
@@ -72,30 +87,45 @@ You can use `xcstrings --help` or `xcstrings <sub-command> --help` to see the li
72
87
  ## Command options
73
88
 
74
89
  * `--help, -h`: `boolean` (Optional)
75
- * Show help.
90
+ * Show help.
76
91
  * `--version, -v`: `boolean` (Optional)
77
- * Show version.
92
+ * Show version.
78
93
  * `--config`: `string` (Optional)
79
- * The custom config file path. If not specified, xcstrings-cli will look for `xcstrings-cli.json` or `xcstrings-cli.json5` in the current folder or its parent folders until the root.
94
+ * The custom config file path. If not specified, xcstrings-cli will look for `xcstrings-cli.json` or `xcstrings-cli.json5` in the current folder or its parent folders until the root.
95
+ * `--path`: `string` (Optional)
96
+ * The xcstrings file path. Defaults to `Localizable.xcstrings` in the current directory, or to the first `xcstringsPaths` entry in the config when present.
97
+ * You can also specify the alias you set in the config file. (`xcstringsPaths` entry with `alias` field)
80
98
 
81
99
  ### `add` command options
82
100
 
83
- * `--strings, -s`: `string | string[] | { [key: string]: string }` (Required)
84
- * The strings to add or update.
85
- * If only one string is provided, xcstrings-cli will use it as the default string.
86
- * `--comment, -c`: `string` (Optional)
87
- * The comment for the string to add, intended for translators.
88
- * `--extractionState, -e`: `string` (Optional, default: `manual`)
89
- * The extraction state of the string to add: `translated` or `manual`.
101
+ * `--key, -k`: `string` (Required)
102
+ * The key of the string to add.
103
+ * `--language, -l`: `string` (Optional)
104
+ * The language of the string provided with `--text`.
105
+ * Ignored if `--text` is not provided.
106
+ * If not specified, it uses the source language defined as `sourceLanguage` in the xcstrings file.
107
+ * Validation follows `missingLanguagePolicy`: `skip` requires the language to be supported; `include` allows any language.
108
+ * `--text`: `string` (Optional)
109
+ * The string value for the language. If omitted, the key is created without a localization for the default language.
110
+ * `--strings`: `string` (Optional)
111
+ * 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).
112
+ * The format is determined by `--strings-format`.
113
+ * `--strings-format`: `string` (Optional, default: `auto`)
114
+ * The format of the data provided with `--strings`. Options are:
115
+ * `auto`: Auto-detect format based on content.
116
+ * `yaml`: YAML format. (It uses `js-yaml` internally.)
117
+ * `json`: JSON format. (It uses `json5` internally.)
118
+ * `--comment`: `string` (Optional)
119
+ * The comment for the string to add, intended for translators.
90
120
 
91
121
  ### `remove` command options
92
122
 
93
123
  * `--key, -k`: `string` (Optional if `languages` is specified)
94
- * The key of the string to remove. If not specified, xcstrings-cli will remove all strings for the specified languages.
124
+ * The key of the string to remove. If not specified, xcstrings-cli will remove all strings for the specified languages.
95
125
  * `--languages, -l`: `string[]` (Optional if `key` is specified)
96
- * The languages to remove. If not specified, xcstrings-cli will remove the string for all languages.
97
- * `--dry-run`: `boolean` (Optional, default: `false`)
98
- * If set to `true`, xcstrings-cli will only show what would be removed without actually removing anything.
126
+ * The languages to remove. If not specified, xcstrings-cli will remove the string for all languages.
127
+ * `--dry-run, -n`: `boolean` (Optional, default: `false`)
128
+ * If set to `true`, xcstrings-cli will only show what would be removed without actually removing anything.
99
129
 
100
130
  ## Config file
101
131
 
@@ -106,8 +136,8 @@ Put an `xcstrings-cli.json5` or `xcstrings-cli.json` file in the project root, a
106
136
  "xcstringsPaths": [
107
137
  "Shared/L10n/Localizable.xcstrings",
108
138
  {
109
- "alias": "utils",
110
- "path": "packages/Utils/Sources/Utils/Resources/Localizable.xcstrings"
139
+ "alias": "utils",
140
+ "path": "packages/Utils/Sources/Utils/Resources/Localizable.xcstrings"
111
141
  }
112
142
  ],
113
143
  "xcodeprojPaths": [
@@ -119,15 +149,15 @@ Put an `xcstrings-cli.json5` or `xcstrings-cli.json` file in the project root, a
119
149
  These are the options for the config file:
120
150
 
121
151
  * **xcstringsPaths**: `string[] | { alias: string, path: string }[]`
122
- * If only one path is provided, xcstrings-cli will use it as the default xcstrings file.
123
- * If multiple paths are provided, xcstrings-cli will ask you to select an xcstrings file.
152
+ * If only one path is provided, xcstrings-cli will use it as the default xcstrings file.
153
+ * If multiple paths are provided, xcstrings-cli will ask you to select an xcstrings file.
124
154
  * **xcodeprojPaths**: `string[]` (Optional)
125
- * Paths to Xcode project files used to detect supported languages.
126
- * If not specified, xcstrings-cli will not check the supported languages in your Xcode project.
155
+ * Paths to Xcode project files used to detect supported languages.
156
+ * If not specified, xcstrings-cli will not check the supported languages in your Xcode project.
127
157
  * **missingLanguagePolicy**: `string` (Optional, default: `skip`)
128
- * How to handle translations for languages that are not included in the `xcstrings languages` output when adding strings. Options are:
129
- * `skip`: Only add translations for languages included in the `xcstrings languages` output.
130
- * `include`: Add translations anyway.
158
+ * How to handle translations for languages that are not included in the `xcstrings languages` output when adding strings. Options are:
159
+ * `skip`: Only add translations for languages included in the `xcstrings languages` output. (Default)
160
+ * `include`: Add translations even when they are not recognized by the Xcode project or xcstrings language list.
131
161
 
132
162
  ## LICENSE
133
163