jsontranslate-cli

English | 简体中文

CLI for uploading JSON locale files to a JsonTranslate workspace, running translation jobs, and syncing translated files back to your project.

English

Install

npm install -g jsontranslate-cli

Or run it without a global install:

npx jsontranslate-cli --help

After installation, use the jsontranslate command:

jsontranslate --help

What It Does

• Authenticates with your JsonTranslate site by browser login or API key
• Initializes a local project and binds it to a remote workspace
• Uploads source locale files
• Starts translation jobs for target locales
• Pulls translated files back into your local i18n directory

Quick Start

1. Log in to your site.

jsontranslate login --site-url https://jsontranslate.org

2. Initialize the current project.

jsontranslate init

3. Upload source files and generate translations.

jsontranslate translate

On first use for a new project, translate scans the source locale directory, uploads source files, creates jobs for every configured target locale, and writes generated target files locally.

If your project already has local target files such as i18n/messages/zh or i18n/messages/ja and you want to keep/import them, run push before translate:

jsontranslate push
jsontranslate translate

4. Pull the latest translated files again later if needed.

jsontranslate pull

Commands

jsontranslate login

Authenticate with your JsonTranslate site.

Options:

• --site-url <siteUrl>: Site base URL
• --method <method>: client or api_key

Example:

jsontranslate login --site-url https://jsontranslate.org --method client

jsontranslate auth:apikey

Save a site API key for CLI requests.

Options:

• --api-key <apiKey>: Site API key
• --site-url <siteUrl>: Site base URL

Example:

jsontranslate auth:apikey --site-url https://jsontranslate.org --api-key sk_xxx

jsontranslate init

Create or bind a remote project and save local CLI config.

Options:

• --site-url <siteUrl>: Site base URL
• --project-name <projectName>: Remote project name
• --source-locale <sourceLocale>: Source locale such as en
• --target-locales <targetLocales>: Comma-separated locales such as zh,ja
• --root-dir <rootDir>: Local i18n directory such as i18n/messages
• --path-pattern <pathPattern>: locale-folder, module-folder, or locale-suffix

Example:

jsontranslate init \
  --site-url https://jsontranslate.org \
  --project-name marketing-site \
  --source-locale en \
  --target-locales zh,ja \
  --root-dir i18n/messages \
  --path-pattern locale-folder

jsontranslate translate

Upload source files, create translation jobs, wait for completion, and write translated files locally.

translate scans only the configured source locale directory, for example i18n/messages/en. It does not use existing local target files to decide what is already translated. The remote workspace decides whether each target locale is missing, up to date, or needs incremental translation.

On a new remote project, this normally creates translations for all configured target locales. To force all target locales to be translated again, use --default-strategy retranslate_all.

Options:

• --default-strategy <strategy>: reuse_uploaded, fill_missing, or retranslate_all

Example:

jsontranslate translate --default-strategy reuse_uploaded

jsontranslate push

Upload local project files to the remote workspace.

Use this when you already have local target locale files and want the remote workspace to reuse them instead of treating those target locales as missing. Unlike translate, push scans the full local i18n directory, including source and target locale files.

Options:

• --default-strategy <strategy>: reuse_uploaded, fill_missing, or retranslate_all

Example:

jsontranslate push --default-strategy reuse_uploaded

jsontranslate pull

Download the latest translated targets from the last bound project or last translation run.

jsontranslate pull

jsontranslate status

Print the current CLI configuration summary.

jsontranslate status

Typical Workflow

New project without existing translations:

jsontranslate login --site-url https://jsontranslate.org
jsontranslate init
jsontranslate translate
jsontranslate status
jsontranslate pull

Existing project with local translations to import first:

jsontranslate login --site-url https://jsontranslate.org
jsontranslate init
jsontranslate push
jsontranslate translate

Local Config

The CLI stores project state in:

.jsontranslate/config.json

This file includes values such as:

• siteUrl
• authType
• projectName
• sourceLocale
• targetLocales
• rootDir
• pathPattern
• lastProjectId
• lastRun

Keep this file in your project root if you want the CLI to continue working with the same remote project.

Notes

• jsontranslate init requires authentication first
• jsontranslate translate, pull, and status require an existing .jsontranslate/config.json
• The default site URL is https://jsontranslate.org
• The installed package name is jsontranslate-cli, but the executable command is jsontranslate

简体中文

用于把本地 JSON 多语言文件上传到 JsonTranslate 工作区、发起翻译任务，并将翻译结果同步回项目的命令行工具。

安装

npm install -g jsontranslate-cli

如果你不想全局安装，也可以直接运行：

npx jsontranslate-cli --help

安装后实际使用的命令是：

jsontranslate --help

功能

• 通过浏览器登录或 API Key 连接 JsonTranslate 站点
• 初始化本地项目并绑定远程工作区
• 上传源语言文件
• 发起目标语言翻译任务
• 将翻译结果拉回本地 i18n 目录

快速开始

1. 登录你的 JsonTranslate 站点。

jsontranslate login --site-url https://jsontranslate.org

2. 初始化当前项目。

jsontranslate init

3. 上传源文件并执行翻译。

jsontranslate translate

新项目第一次使用时，translate 会扫描源语言目录、上传源文件、为配置里的所有目标语言创建翻译任务，并把生成的目标语言文件写回本地。

如果你的项目本来就有 i18n/messages/zh 或 i18n/messages/ja 这类本地目标语言文件，并且想保留/导入这些已有翻译，请先执行 push，再执行 translate：

jsontranslate push
jsontranslate translate

4. 之后如果只想重新同步翻译结果，可以执行：

jsontranslate pull

命令说明

jsontranslate login

登录 JsonTranslate 站点。

参数：

• --site-url <siteUrl>：站点地址
• --method <method>：client 或 api_key

示例：

jsontranslate login --site-url https://jsontranslate.org --method client

jsontranslate auth:apikey

保存站点 API Key，供 CLI 请求使用。

参数：

• --api-key <apiKey>：站点 API Key
• --site-url <siteUrl>：站点地址

示例：

jsontranslate auth:apikey --site-url https://jsontranslate.org --api-key sk_xxx

jsontranslate init

创建或绑定远程项目，并保存本地 CLI 配置。

参数：

• --site-url <siteUrl>：站点地址
• --project-name <projectName>：远程项目名称
• --source-locale <sourceLocale>：源语言，例如 en
• --target-locales <targetLocales>：逗号分隔的目标语言，例如 zh,ja
• --root-dir <rootDir>：本地 i18n 目录，例如 i18n/messages
• --path-pattern <pathPattern>：locale-folder、module-folder 或 locale-suffix

示例：

jsontranslate init \
  --site-url https://jsontranslate.org \
  --project-name marketing-site \
  --source-locale en \
  --target-locales zh,ja \
  --root-dir i18n/messages \
  --path-pattern locale-folder

jsontranslate translate

上传源文件、创建翻译任务、等待任务完成，并把翻译后的文件写回本地。

translate 只扫描配置里的源语言目录，例如 i18n/messages/en。它不会读取本地已有的目标语言文件来判断是否已经翻译；是否缺失、是否最新、是否需要增量翻译，都由远程工作区里的记录决定。

对于一个新的远程项目，translate 通常会为所有配置的目标语言生成翻译。如果你想强制所有目标语言重新翻译，可以使用 --default-strategy retranslate_all。

参数：

• --default-strategy <strategy>：reuse_uploaded、fill_missing 或 retranslate_all

示例：

jsontranslate translate --default-strategy reuse_uploaded

jsontranslate push

把本地项目文件上传到远程工作区。

当你本地已经有目标语言文件，并希望远程工作区复用这些翻译时，请使用 push。和 translate 不同，push 会扫描完整的本地 i18n 目录，包括源语言和目标语言文件。

参数：

• --default-strategy <strategy>：reuse_uploaded、fill_missing 或 retranslate_all

示例：

jsontranslate push --default-strategy reuse_uploaded

jsontranslate pull

从最近绑定的远程项目，或最近一次翻译任务中拉取目标语言文件。

jsontranslate pull

jsontranslate status

输出当前 CLI 配置摘要。

jsontranslate status

典型流程

没有现成翻译的新项目：

jsontranslate login --site-url https://jsontranslate.org
jsontranslate init
jsontranslate translate
jsontranslate status
jsontranslate pull

已有本地翻译、希望先导入远程工作区的项目：

jsontranslate login --site-url https://jsontranslate.org
jsontranslate init
jsontranslate push
jsontranslate translate

本地配置文件

CLI 会把项目状态保存到：

.jsontranslate/config.json

里面会包含这些信息：

• siteUrl
• authType
• projectName
• sourceLocale
• targetLocales
• rootDir
• pathPattern
• lastProjectId
• lastRun

如果你希望 CLI 后续继续操作同一个远程项目，不要删除项目根目录下的这个文件。

说明

• jsontranslate init 之前必须先完成认证
• jsontranslate translate、pull、status 都依赖已有的 .jsontranslate/config.json
• 默认站点地址是 https://jsontranslate.org
• npm 包名是 jsontranslate-cli，实际命令名是 jsontranslate

License

MIT