Translate Lottie animation text with Hyperlocalise

• .json: the CLI detects Lottie by content. A .json file whose root has v, fr, ip, op, and layers is treated as a Lottie animation rather than a JSON localization file.
• .lottie: dotLottie zip archives. Every animation under animations/ (dotLottie 1.0) or a/ (dotLottie 2.0) is translated.

​

Source file

{"v":"5.7.4","fr":30,"ip":0,"op":90,"w":512,"h":512,"layers":[
  {"ty":5,"nm":"Headline","t":{"d":{"k":[{"s":{"s":48,"f":"Inter-Bold","t":"Save more\rtoday","j":0},"t":0}]}}}
]}

​

Configure your files

locales:
    source: en-US
    targets:
        - es-ES

buckets:
    animations:
        files:
            - from: animations/en-US/promo.json
              to: animations/{{target}}/promo.json

llm:
    profiles:
        default:
            provider: openai
            model: gpt-5.2

​

Translate

hyperlocalise run --dry-run
hyperlocalise run

buckets:
    animations:
        files:
            - from: animations/en-US/promo.lottie
              to: animations/{{target}}/promo.lottie

​

Behavior and limitations

• Only text layers (ty: 5) are translated, including text layers inside precompositions (assets[].layers). Keys are JSON paths such as layers[1].t.d.k[0].s.t.
• Each text keyframe is one translation unit. The layer name, precomposition ID, and keyframe frame are supplied as translation context.
• Lottie encodes line breaks as \r. The translation keeps them as \r.
• Writeback always starts from the source animation and replaces only the text string values. Formatting, number precision, and key order are preserved byte-for-byte.
• Text converted to shapes cannot be translated. Only editable text layers are extracted.
• Animations that embed glyphs (chars) only render characters that have glyph outlines. Use a font that covers the target script, or export without embedded glyphs.
• In .lottie archives, keys are prefixed with the animation entry, such as a/promo.json#layers[1].t.d.k[0].s.t. The target archive is rebuilt from the source archive. Only animations with translated text are rewritten; the manifest, images, themes, and state machines are copied unchanged.
• Theme or slot overrides inside dotLottie archives are not translated.
• Translated text can overflow the original text box or layout. Review the rendered animation for each locale.

​

Next steps

• Check translations before committing generated files.
• Local translation workflow explains repeat runs.
• Browse all file formats.

​

Related formats

• JSON localization