# gt: General Translation CLI tool: Lottie
URL: https://generaltranslation.com/en-US/docs/cli/reference/formats/lottie-files.mdx
---

title: Lottie
description: Translate dotLottie animation files with the General Translation CLI. API reference for the Lottie file format.

---

The CLI translates text in binary dotLottie (`.lottie`) animation files and writes each result as a complete `.lottie` file. Lottie jobs include an asynchronous layout-processing phase, so they use the split stage-and-download workflow.

## Overview [#overview]

| Topic | Description |
| --- | --- |
| [Configuration](#config) | Configure source and translated `.lottie` paths. |
| [Translation workflow](#workflow) | Stage asynchronous work and download completed animations. |
| [Layout processing](#layout) | Fit translated text while preserving the animation's design. |
| [Expressions](#expressions) | Remove executable After Effects expressions before translation. |
| [Fonts](#fonts) | Upload fonts used during translated layout processing. |
| [Binary output](#binary) | Handle base64 transport and decoded `.lottie` files. |

## Configuration [#config]

Add a `lottie` entry under `files` with an `include` array of glob patterns. Use the `[locale]` placeholder so the CLI can find source animations and save translated files under each target locale.

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

With this config, source animations come from `animations/en/`, and translated animations are saved under `animations/es/` and `animations/fr/`. See the [configuration reference](/docs/cli/reference/config#files) for the shared file keys.

## Translation workflow [#workflow]

Run [`gt stage`](/docs/cli/reference/commands/stage) to submit the animations, then run [`gt download`](/docs/cli/reference/commands/download) until every locale has finished:

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

Translations that are still processing are skipped. Re-run [`gt download`](/docs/cli/reference/commands/download) later to fetch them; the staged entry remains in `gt-lock.json` until every configured locale is downloaded.

[`gt translate`](/docs/cli/reference/commands/translate) cannot complete an unstaged Lottie job in one run. When `stageTranslations` is `false` and the config includes Lottie files, it exits with guidance to use [`gt stage`](/docs/cli/reference/commands/stage) and [`gt download`](/docs/cli/reference/commands/download).

## Layout processing [#layout]

Layout processing preserves the animation's font sizes. It reflows text and adjusts nearby layers to fit translated labels. When a label still does not fit, the process may shorten or rephrase it in the target language while preserving its meaning. Truncation with an ellipsis is the last fallback.

If layout changes cannot be rendered and verified, the job completes with the base translated animation instead of applying unverified changes. Review the downloaded animation before publishing it.

## Expressions [#expressions]

Lottie files with After Effects expressions are rejected because expressions contain executable JavaScript. Re-export the animation with expressions removed or baked into keyframes, then stage it again.

## Fonts [#fonts]

Add a top-level [`fonts`](/docs/cli/reference/config#fonts) configuration when an animation uses fonts that may not be available during layout processing:

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

The CLI uploads matching fonts before it queues translation jobs. If a font cannot be synced, translation continues with fallback fonts and emits a warning.

## Binary output [#binary]

The CLI carries `.lottie` files as base64 internally, then decodes downloaded results back to binary files. Do not treat the downloaded content as UTF-8 text or hand-edit the intermediate base64 data.