# @fieldlyab/translator-cli 中文文档

规范地址：https://npmcn.com/package/%40fieldlyab/translator-cli/

版本：0\.13\.0
npm 元数据更新时间：2026-10-19T06:24:58.292Z
中文译文更新时间：2026-11-14T17:20:58.931Z
软件包许可：UNLICENSED

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fieldlyab/translator-cli
原文对照：https://npmcn.com/package/%40fieldlyab/translator-cli/?lang=original
项目主页：https://ft.fieldly.com/

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：84.6 kB，3 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=18
- 运行依赖：1 个
- 首次发布：2026-07-12T15:47:32.785Z
- 最新版本发布：2026-10-19T06:24:58.107Z
- 近 30 天下载量：4381（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 17 个）

## 中文简介

外地翻译开发者CLI (ft)——在repos和外地翻译之间进行push/pull/status翻译.

## 安装

```sh
npm install @fieldlyab/translator-cli
```

也可以使用：`pnpm add @fieldlyab/translator-cli`、`yarn add @fieldlyab/translator-cli`、`bun add @fieldlyab/translator-cli`

## README

# `ft` - 外地笔译员

您的 repo 翻译文件与 Fieldly 之间的命令行传输 翻译 (FT). 这个 **不解析翻译格式** 它读取原始文件 在已配置的路径和 POSTs/ GETs 中; FT 的服务器侧引擎处理每个 格式(Rails YAML、ngx- translate/Transloco JSON、Android XML、iOS) 字符串/字符串/xcstrings).

跨站台(macOS / Windows / Linux)通过Node 18.

**外地翻译 :** [ft.fieldly.com (英语)](https://ft.fieldly.com/)

## 安装

```
npm install -g @fieldlyab/translator-cli
```

或不安装而运行 :

```
npx @fieldlyab/translator-cli login
```

二进制同时曝光 `ft` 财务报告和审定财务报表 `fieldly-translator`。 。 。 .

## 所需资源

现场翻译为 **现在只邀请** ——没有自助服务 注册到现在,所以自己安装这个CLI并不能允许访问. 惠璶 一个来自Fieldly的管理员已添加的外地翻译账户. 如果您无法访问,请联系您的外地翻译管理员.

运行 `ft` 从拥有 `fieldly-translator.yml` 文档的根.

## 图标

```
ft login   [--token [T]] [--host URL]              sign in via browser SSO, or paste a token
ft push    [--locales L] [--branch B] [--force] [--dry-run]  send new/changed source+authored keys up
ft pull    [--locales L] [--branch B] [--release V] [--force] [--dry-run]  write FT-owned target locales
ft status  [--branch B] [--locales L] [--min-status S]  report completeness; non-zero exit gates CI
ft get     KEY [--locale L] [--namespace N]         fetch a single key
ft set     KEY code="text" [...] [--branch B] [--namespace N] [--status S] [--no-write|--write]  hand-fill locale values on a key
ft create  KEY "Source" [code="text" ...] [--branch B] [--namespace N] [--description D] [--status S] [--no-write|--write] [--wait]  create a key with source + values
ft config  push | check                             apply this repo's locale roles to FT, or report drift
ft init    PROJECT [--force]                        write a fieldly-translator.yml from the project
ft request [--locales L] [--all] [--branch B]       trigger translations for missing targets; --branch fills just that branch's keys

ft --version | -v                                   print the ft version
ft --help    | -h                                   show usage
```

此列表不命名为 **使用错误** (exit 2),从来没有什么 `ft` 倒在地上——建议使用最接近的正版旗帜. 在0.1.2.0 a之前 未识别旗被接受和忽略,所以 `ft pull --brnach x` 安静 拉活头和 `ft pull --dry-runn` 安静 _写_ 您的语言文件. `--flag=value` 工作与 `--flag value`,而一面布尔旗不再 吞后语.

CLI发送 `User-Agent: ft/<version>` 每次请求时,服务器都会回答 与最古老的版本 它认为安全。 如果你在下面的话, `ft` 打印 a 警告stderr 命名有危险的东西——每次运行一次,永远不要改变退出 代码,永远不要屏蔽命令。 只有在更老的CLI时,地板才会移动 将破坏重播或丢失数据, 而不是用于新的特性.

运行 `ft <command> --help` 用于完整选项列表.

## 在专题分部工作

命名您的分行和字符串 一个功能添加了远离其他人的方式 至于船舶

```bash
ft push --branch fp-1234-new-quotes     # new keys are STAGED on that branch
ft create checkout.title "Checkout" --branch fp-1234-new-quotes
ft pull --branch fp-1234-new-quotes     # main + branch: your branch's strings included
ft status --branch fp-1234-new-quotes   # gate CI on just this feature's strings
ft request --branch fp-1234-new-quotes  # AI-fill what's missing on just this branch's keys
```

键 **诞生** 下级 `--branch` 由 AI 和 照常审查,但缺席 `ft pull` 主要出口和出口 完整性——直到有人将分行合并到FT中去,这促进了分行的生存. 所以一个延迟的功能只是一个未出现的分支, 没有半完成的文字 漏入出产.

舞台上的钥匙仍由你负责: `ft get` 财务报告和审定财务报表 `ft set` 找到这个 名称是否为 `--branch` (一个名字是独一无二的) 分部门)和 `ft request --branch B` 计数并填充 B 的密钥——这些密钥 它推动、创建或编辑——而不是整个项目的积压,因为 完全无法看到已设置的密钥, 并且会按密钥名称使用其每50个运行的上限 . 未知的分支名称被拒绝 与一个做 - you - 意思,比如 `ft status`。 。 。 .

`ft pull --branch B` 是开发者的观点:活头 **加号** B级 舞台键, 由 B 的舞台编辑 压倒性头值—— 所有 合并 将产生。 一个平地 `ft pull` 保持纯正活生生的头. `--branch` 财务报告和审定财务报表 `--release` 是相互排斥的:释放是不可改变的快照.

命名一个 FT 从未听说过的分支 **没有** 失败拉出-"main + 树枝" 树枝没有贡献 只是活头,所以 `ft pull --branch $(git branch --show-current)` 在分支上的脚本中是安全的 这还没有设置一个关键。 它警告和命名 分支你的意思,所以 字型仍然很明显

```
Branch "fp-4048-quotes-calclation" is not in FT — pulling live head only.
  Did you mean "fp-4048-quotes-calculation"?
```

比赛的服务器侧面 横跨每一个开放的分支, 所以它找到一个你 意思是说它早就被推了 当没有什么是接近 成为一个 type, 不提供猜测, 而项目的开放式分支被列出 .

`ft status --branch` 更严格,而且仍然 **失败** 在一个未知分支上: 后退是0键以上的门, 它通过CI绿色的分枝 没有人检查。 也叫那个分支,所以失败告诉你 怎样修复.

将值写入密钥 **已经存在** 现场直播`ft set --branch`, (中文(简体) ), 或者说 `ft push --branch` 超过未变的密钥 ) 正在运行中 —— 值被激活 立即记录分行的报告 所以 `ft status --branch` 和GitHub PR检查 覆盖它.

手填的目标值为 `needs_review` 默认; `--status` 实值 很荣幸你通过SSO签约 拥有编辑权. 人工智能填充(`ft request`)只填充缺失的值,所以它永远不会覆盖 所设置的.

这两个命令还更新了映射的本地文件( skip with `--no-write`: 目标文件像范围重导 `ft pull`,而重新拥有 源文件只得到所复制的新密钥 —— 您未打印的源编辑 生存下来。 YAML/JSON格式仅限目前.

你想要多少是一个环境, 因为两者的一半成本非常高 不同的是,连线是局部的,即时的,目标再出口是一个 请求(当地,文件块),所以批次 `ft create`大部分时间花在 重新下载的时间目录 :

```yaml
local_write: all        # all (default) | authored | off
```

`authored` 将相接文件保存到下一个 `ft pull`· ; `off` 写什么。 每一次运行, `--no-write` 表示 `off` 财务报告和审定财务报表 `--write` 表示 `all`不管文件怎么说.

`ft pull` (和本地写作的目标一半) **合并** 而不是说 覆盖: 条目 FT 无法存储 – Rails' `date.day_names`, (中文(简体) ), `number.format. precision`,以及所报的未跳过的非字符串值—— 保存在文件中。 FT仍然在每把钥匙上取胜,所以一个键FT掉了 仍然消失,一个没有保存的文件被写成 导出.

## 配置

单人 `fieldly-translator.yml` 在 repo 根上声明 FT 项目 locale 角色( 源/ 作者/ 目标), 和 翻译文件路径, 每张 平台和应用程序.

当 repo 的文件名与 FT 的 Cononical 地块代码有分歧时—— Rails 写 `en_au.yml`,FT存储 BCP-47 `en-AU` ——按格式块绘制地图:

```yaml
targets: [en-AU]                   # the CANONICAL code
formats:
  - platform: rails
    format: rails-yaml
    path: config/locales/{locale}.yml
    locale_map:
      en-AU: en_au                 # canonical -> on-disk filename
```

`locale_map` 更改 **仅文件名**,从不包含文件内容。 声明 磁盘上的拼写 `targets:` 而不是在 FT 中创建第二个语言,以及 然后把同一种语言的翻译分成两部分.

## 常见问题

### @fieldlyab/translator-cli 是什么？

外地翻译开发者CLI \(ft\)——在repos和外地翻译之间进行push/pull/status翻译\.

### 如何安装 @fieldlyab/translator-cli？

在项目目录运行 npm install @fieldlyab/translator-cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 ft、fieldly-translator，可以用 npx ft 直接运行。

### @fieldlyab/translator-cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/fieldlyab\_\_translator-cli 是否存在。

### @fieldlyab/translator-cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @fieldlyab/translator-cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @fieldlyab/translator-cli 可以商用吗？

@fieldlyab/translator-cli 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @fieldlyab/translator-cli 的下载量有多少？

根据 npm 官方下载统计，@fieldlyab/translator-cli 在 2026/10/15 – 2026/11/13 这 30 天内被下载 4,381 次，日均约 146 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fieldlyab/translator-cli 还在维护吗？

最新版本 0\.13\.0 发布于 2026/10/19（26 天前）；至今共发布 17 个版本，其中过去 12 个月发布了 17 个；首次发布于 2026/07/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。