# gt: General Translation CLI tool: Lottie
URL: https://generaltranslation.com/zh/docs/cli/reference/formats/lottie-files.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 使用 General Translation CLI 翻译 dotLottie 动画文件。Lottie 文件格式的 API 参考。

CLI 可翻译二进制 dotLottie (`.lottie`) 动画文件中的文本，并将每个结果输出为完整的 `.lottie` 文件。Lottie 任务包含异步布局处理阶段，因此采用分步暂存和下载工作流。

## 概览 [#overview]

| 主题                  | 说明                                   |
| ------------------- | ------------------------------------ |
| [配置](#config)       | 配置源 `.lottie` 文件和译文 `.lottie` 文件的路径。 |
| [翻译工作流程](#workflow) | 暂存异步任务并下载已完成的动画。                     |
| [布局处理](#layout)     | 在保留动画设计的同时调整译文文本。                    |
| [表达式](#expressions) | 翻译前移除可执行的 After Effects 表达式。         |
| [字体](#fonts)        | 上传译文布局处理时使用的字体。                      |
| [二进制输出](#binary)    | 处理 base64 传输和解码后的 `.lottie` 文件。      |

## 配置 [#config]

在 `files` 下添加一个 `lottie` 条目，并设置包含 glob 模式的 `include` 数组。使用 `[locale]` 占位符，以便 CLI 查找源动画，并将翻译后的文件保存到各目标区域设置对应的目录下。

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "files": {
    "lottie": {
      "include": ["animations/[locale]/**/*.lottie"],
      "exclude": ["animations/[locale]/drafts/**"]
    }
  }
}
```

使用此配置，源动画位于 `animations/en/`，翻译后的动画会保存至 `animations/es/` 和 `animations/fr/`。有关共享文件键，请参阅[配置参考](/docs/cli/reference/config#files)。

## 翻译工作流程 [#workflow]

运行 [`gt stage`](/docs/cli/reference/commands/stage) 提交动画，然后运行 [`gt download`](/docs/cli/reference/commands/download)，直到所有区域设置的翻译完成：

```bash
npx gt stage
npx gt download
```

仍在处理的翻译会被跳过。请稍后重新运行 [`gt download`](/docs/cli/reference/commands/download) 以下载它们；暂存的条目会保留在 `gt-lock.json` 中，直到所有已配置的区域设置均已下载完成。

[`gt translate`](/docs/cli/reference/commands/translate) 无法在一次运行中完成未暂存的 Lottie 作业。当 `stageTranslations` 为 `false` 且配置中包含 Lottie 文件时，该命令会退出，并提示使用 [`gt stage`](/docs/cli/reference/commands/stage) 和 [`gt download`](/docs/cli/reference/commands/download)。

## 布局处理 [#layout]

布局处理会保留动画中的字体大小。它会重新排布文本，并调整相邻图层，以容纳翻译后的标签。如果标签仍无法容纳，系统可能会在保留原意的前提下，以目标语言缩短或改写标签。使用省略号截断是最后的后备方案。

以等宽文本样式呈现的代码 token 不会被缩短或改写。普通文字注释仍可能被改写以适应布局。

如果无法渲染并验证布局更改，job 将以基础翻译后的动画完成，而不会应用未经验证的更改。请在发布前审校下载的动画。

## 表达式 [#expressions]

包含 After Effects 表达式的 Lottie 文件会被拒绝，因为表达式中包含可执行的 JavaScript。请移除表达式或将其烘焙为关键帧后重新导出动画，然后再次暂存。

## 字体 [#fonts]

如果动画使用的字体在布局处理时可能无法使用，请添加顶层 [`fonts`](/docs/cli/reference/config#fonts) 配置：

```json title="gt.config.json"
{
  "fonts": {
    "include": ["public/fonts/**/*.{ttf,otf}"]
  }
}
```

CLI 会在将翻译任务排队前上传匹配的字体。如果某个字体无法同步，翻译将继续使用后备字体，并发出警告。

## 二进制输出 [#binary]

CLI 在内部以 base64 格式传输 `.lottie` 文件，然后将下载结果解码为二进制文件。请勿将下载的内容当作 UTF-8 文本处理，也不要手动编辑中间的 base64 数据。

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.