{"id":44947633,"url":"https://github.com/mshibanami/xcstrings-cli","last_synced_at":"2026-02-18T10:00:56.736Z","repository":{"id":327933722,"uuid":"1111757069","full_name":"mshibanami/xcstrings-cli","owner":"mshibanami","description":"CLI command \"xcs\" for working with String Catalog (xcstrings).","archived":false,"fork":false,"pushed_at":"2025-12-10T11:35:24.000Z","size":198,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-10T12:58:32.190Z","etag":null,"topics":["i18n","ios","macos","string-catalog","typescript","xcode","xcstrings"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mshibanami.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-07T15:25:24.000Z","updated_at":"2025-12-10T11:34:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mshibanami/xcstrings-cli","commit_stats":null,"previous_names":["mshibanami/xcstrings-cli"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/mshibanami/xcstrings-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mshibanami%2Fxcstrings-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mshibanami%2Fxcstrings-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mshibanami%2Fxcstrings-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mshibanami%2Fxcstrings-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mshibanami","download_url":"https://codeload.github.com/mshibanami/xcstrings-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mshibanami%2Fxcstrings-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29575343,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T08:38:15.585Z","status":"ssl_error","status_checked_at":"2026-02-18T08:38:14.917Z","response_time":162,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["i18n","ios","macos","string-catalog","typescript","xcode","xcstrings"],"created_at":"2026-02-18T10:00:31.387Z","updated_at":"2026-02-18T10:00:56.725Z","avatar_url":"https://github.com/mshibanami.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xcstrings-cli (`xcs`)\n\n[![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)\n\nThis is a command-line tool designed for working with **String Catalog** (`.xcstrings`) files, such as adding and removing localized strings. It supports JSON5 and YAML formats for inputting translations.\n\nWe also provide a Custom GPT that can help you generate translations and output them in the form of an `xcs` command. Check it out here: [xcstrings-cli Helper](https://chatgpt.com/g/g-69365945f8bc8191be3146f880238957-xcstrings-cli-helper). (The configuration is in [helpers/helper-config.md](./helpers/helper-config.md).)\n\n## Installation\n\n1. Install xcstrings-cli using npm:\n    ```bash\n    npm install -g xcstrings-cli\n    ```\n\n    This will install the `xcs` command globally.\n\n2. Create a [configuration file](#configuration-file) for your project by running:\n    ```bash\n    xcs init\n    ```\n\n    This will ask you some questions and create an `xcstrings-cli.yaml` file in the current directory.\n\n## Usage\n\n**Add a string:**\n\n```bash\n# Add with key, comment, and default language string\nxcs add --key greeting --comment \"A greeting message.\" --text \"Hello, World.\"\n\n# Add with key, comment, and translations YAML via heredoc\nxcs add \\\n    --key greeting \\\n    --comment \"A greeting message.\" \\\n    --strings \u003c\u003c EOF\nen: Hello, World.\nja: こんにちは、世界。\nzh-Hans: 你好，世界。\nEOF\n\n# Or add translations JSON\nxcs add \\\n    --key greeting \\\n    --comment \"A greeting message.\" \\\n    --strings \u003c\u003c EOF\n{\n    \"en\": \"Hello, World.\",\n    \"ja\": \"こんにちは、世界。\",\n    \"zh-Hans\": \"你好，世界。\"\n}\nEOF\n\n# Start interactive mode to add translations using `$EDITOR` environment variable (e.g. `vim`)\nxcs add -i\n\n# Add translations via file\nxcs add \\\n    --key greeting \\\n    --comment \"A greeting message.\" \\\n    --strings-format yaml \\\n    --strings \u003c translations.yaml\n\n# Add multiple strings via heredoc\nxcs add --strings \u003c\u003c EOF\ngreeting:\n    translations:\n        en: Hello, World.\n        ja:\n            state: needs_review\n            value: こんにちは、世界。\n        zh-Hans: 你好，世界。\n    comment: A greeting message.\nfarewell:\n    translations:\n        en: Goodbye, World.\n        ja:\n            state: needs_review\n            value: さよなら、世界。\n        zh-Hans:\n            state: stale\n            value: さようなら、世界。\n    comment: A farewell message.\nEOF\n\n# Add with only key and comment\nxcs add --key greeting --comment \"A greeting message.\"\n```\n\n**Remove a string:**\n\n```bash\nxcs remove --key greeting\n```\n\n**Remove all strings of specific languages:**\n\n```bash\nxcs remove --languages ja zh-Hans\n```\n\n**List supported languages:**\n\nIf `xcodeprojPaths` is configured, this command lists languages from your Xcode project (knownRegions) and excludes `Base`. Otherwise, it lists languages appeared in the xcstrings file.\n\n```bash\nxcs languages\n# en ja zh-Hans\n```\n\n**List strings in the xcstrings file:**\n\n```bash\n# List all strings\nxcs strings\n# helloWorld:\n#   en: \"Hello, World.\"\n#   ja: \"こんにちは、世界。\"\n#   zh-Hans: \"你好，世界。\"\n# goodbyeWorld:\n#   en: \"Goodbye, World.\"\n#   ja: \"さようなら、世界。\"\n# goodMorning:\n#   en: \"Good morning.\"\n#   ja: \"おはようございます。\"\n# ... etc.\n\n# List strings filtered by key\nxcs strings --key good*\n# goodbyeWorld:\n#   ...\n# goodMorning:\n#   ...\n\n# List strings filtered by language\nxcs strings --languages en\n# helloWorld:\n#   en: \"Hello, World.\"\n# goodbyeWorld:\n#   en: \"Goodbye, World.\"\n# goodMorning:\n#   en: \"Good morning.\"\n# ... etc.\n\n# List strings with custom format\nxcs strings --format \"[{{language}}] {{key}} =\u003e {{text}}\"\n# [en] helloWorld =\u003e \"Hello, World.\"\n# [ja] helloWorld =\u003e \"こんにちは、世界。\"\n# [en] goodbyeWorld =\u003e \"Goodbye, World.\"\n# [ja] goodbyeWorld =\u003e \"さようなら、世界。\"\n# ... etc.\n```\n\nYou can use `xcs --help` or `xcs \u003csub-command\u003e --help` to see the list of commands and options.\n\n## Commands\n\n**Global options:**\n\n* `--config`: `string` (Optional)\n    * 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.\n* `--help, -h`: `boolean` (Optional)\n    * Show help.\n* `--path`: `string` (Optional)\n    * The xcstrings file path. Defaults to `Localizable.xcstrings` in the current directory, or to the first `xcstringsPaths` entry in the config when present.\n    * You can also specify the alias you set in the config file. (`xcstringsPaths` entry with `alias` field)\n* `--version, -v`: `boolean` (Optional)\n    * Show version.\n\n### `add` command\n\nAdds/updates one or more strings to the xcstrings file.\n\n**`add` command options:**\n\n* `--comment`: `string` (Optional)\n    * The comment for the string to add, intended for translators.\n* `--interactive, -i`: `boolean` (Optional)\n    * Start interactive mode to add strings.\n    * This is useful when you don't want to record a huge command to your terminal history.\n* `--key, -k`: `string` (Required unless `--strings` contains one or more keys)\n    * The key of the string to add.\n* `--language, -l`: `string` (Optional)\n    * The language of the string provided with `--text`.\n    * Ignored if `--text` is not provided.\n    * If not specified, it uses the source language defined as `sourceLanguage` in the xcstrings file.\n    * Validation follows `missingLanguagePolicy`: `skip` requires the language to be supported; `include` allows any language.\n* `--state`: `string` (Optional, default: `translated`)\n    * Values applied to single-key and multi-key adds: `translated`, `needs_review`, `new`, `stale`. If omitted, strings default to `translated`.\n    * Multi-key payloads can also set per-language states with `{ state, value }`; string shorthand is treated as `translated`.\n    * Available states: `translated`, `needs_review`, `new`, `stale`\n* `--strings`: `string` (Optional)\n    * 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).\n    * The format is determined by `--strings-format`.\n* `--strings-format`: `string` (Optional, default: `auto`)\n    * The format of the data provided with `--strings`. Options are:\n        * `auto`: Auto-detect format based on content.\n        * `yaml`: YAML format.\n        * `json`: JSON format. JSON5 is also supported.\n* `--text`: `string` (Optional)\n    * The string value for the language. If omitted, the key is created without a localization for the default language.\n\n### `remove` command\n\nRemoves strings from the xcstrings file based on the specified filter options.\n\n**`remove` command options:**\n\n* `--dry-run, -n`: `boolean` (Optional, default: `false`)\n    * If set to `true`, `xcs` will only show what would be removed without actually removing anything.\n* `--key, -k`: `string` (Optional if `languages` is specified)\n    * The key of the string to remove. If not specified, xcstrings-cli will remove all strings for the specified languages.\n* `--languages, -l`: `string[]` (Optional if `key` is specified)\n    * The languages to remove. If not specified, `xcs` will remove the string for all languages.\n\n### `strings` command\n\nLists strings in the xcstrings file, with optional filtering and formatting.\n\n**`strings` commands options:**\n\n* `--format`: `string` (Optional)\n    * Mustache template for per-localization output. Available variables: `{{language}}`, `{{key}}`, `{{text}}`.\n* `--key`, `--key-glob`: `string` (Optional)\n    * Filter keys by glob pattern. This is the default key filter mode.\n* `--key-regex`: `string` (Optional)\n    * Filter keys by regular expression.\n* `--key-substring`: `string` (Optional)\n    * Filter keys by substring match.\n* `--languages, -l`: `string[]` (Optional)\n    * Include only the specified languages.\n* `--text`, `--text-glob`: `string` (Optional)\n    * Filter translations by glob pattern. This is the default text filter mode.\n* `--text-regex`: `string` (Optional)\n    * Filter translations by regular expression.\n* `--text-substring`: `string` (Optional)\n    * Filter translations by substring match.\n\n## Configuration file\n\nPut a config file named `xcstrings-cli` in the project root, using one of the following extensions:\n\n- `.json`: JSON format\n- `.json5`: JSON5 format\n- `.yml` `.yaml`: YAML format\n\nHere is an example config file in JSON format:\n\n```json\n{\n    \"missingLanguagePolicy\": \"include\",\n    \"xcstringsPaths\": [\n        \"Shared/L10n/Localizable.xcstrings\",\n        {\n            \"alias\": \"utils\",\n            \"path\": \"packages/Utils/Sources/Utils/Resources/Localizable.xcstrings\"\n        }\n    ],\n    \"xcodeprojPaths\": [\n        \"path/to/your/Project.xcodeproj\"\n    ]\n}\n```\n\nThese are the settings you can specify in the config file:\n\n* **missingLanguagePolicy**: `string` (Optional, default: `skip`)\n    * How to handle translations for languages that are not included in the `xcs languages` output when adding strings. Options are:\n    * `skip`: Only add translations for languages included in the `xcs languages` output. (Default)\n    * `include`: Add translations even when they are not recognized by the Xcode project or xcs language list.\n* **xcodeprojPaths**: `string[]` (Optional)\n    * Paths to Xcode project files (`.xcodeproj`) used to detect supported languages.\n    * If not specified, `xcs` will only check the xcstrings file to detect supported languages.\n* **xcstringsPaths**: `(string | { alias: string; path: string })[]` (Optional)\n    * Paths to xcstrings files used by `xcs`.\n    * If only one path is provided, `xcs` will use it as the default xcstrings file.\n    * If multiple paths are provided, `xcs` will ask you to select an xcstrings file.\n    * You can also specify an alias, and use it with the `--path` option.\n\n## Practical use cases\n\n### Case 1: Translate all missing strings using LLM\n\nSuppose you have a xcstrings file and want to add Japanese and Simplified Chinese translations generated by LLM.\n\nFirstly, list the strings missing those languages:\n\n```bash\nxcs strings --languages en --missing-languages ja zh-Hans\n# closeAction:\n#   en: \"Close\"\n# detailsAction:\n#   en: \"Details\"\n```\n\nThen, copy the output and use it as a prompt for the LLM to generate translations. We offer [xcstrings-cli Helper](https://chatgpt.com/g/g-69365945f8bc8191be3146f880238957-xcstrings-cli-helper), a Custom GPT that can help you generate translations in the form of an `xcs add` command. The prompt could be like this:\n\n```\ncloseAction:\n  en: \"Close\"\ndetailsAction:\n  en: \"Details\"\n\nLanguages: ja, zh-Hans\nNo comments needed.\n```\n\nThen the Custom GPT will generate YAML like this:\n\n```yaml\ncloseAction:\n    translations:\n        en: Close\n        ja: 閉じる\n        zh-Hans: 关闭\ndetailsAction:\n    translations:\n        en: Details\n        ja: 詳細\n        zh-Hans: 详情\n```\n\nFinally, copy the generated YAML and run `xcs add -i` to add the translations to your xcstrings file via interactive mode.\n\n## Q\u0026A\n\n**Q: Strings are not being added for some languages. Why?**\n\nA: 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`.\n\nIf you want to add translations for languages not included in your Xcode project, you can change the `missingLanguagePolicy` in your config file to `include`.\n\n## LICENSE\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmshibanami%2Fxcstrings-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmshibanami%2Fxcstrings-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmshibanami%2Fxcstrings-cli/lists"}