Lottie text-layer translation QA means changing the visible words inside a Lottie animation while keeping its layer timing, motion, font references, text keyframes and interactive meaning coherent. The immediate answer is to identify actual text documents rather than editing every JSON string, translate only approved visible copy, preserve animation structures, and render the result in every target player. A JSON parser can confirm the file has valid syntax; it cannot tell whether a longer phrase was cut off halfway through a six-frame animation.
A short animated graphic in a classroom app might show “Read the question,” then “Check your evidence,” before a button appears. Another team may need the same animation in Tamil, Mandarin or Malay. The challenge is not simply replacing three English phrases. The text may be an animated layer with multiple document keyframes, a font that lacks target-script glyphs, or shapes rather than editable characters. A correct localized message can still fail if it appears too late, collides with a moving illustration or becomes invisible on a small screen.
The practical workflow is to inventory the file’s text layers, keyframes, fonts, precompositions and renderer dependencies; freeze the motion and timing contract; translate a reviewed copy table; patch only the intended text-bearing fields; then compare structural fields and render visual fixtures at important frames. This method offers a useful balance between repeatable mechanical checks and the human judgment needed for language, motion and comprehension.
What a Lottie JSON file contains
Lottie JSON describes an animation’s composition, layers, timing, transforms and assets. It can contain vector shapes, text, raster references and precompositions; renderers use this data to draw successive frames. Text is not necessarily stored as one obvious top-level label. A text layer can have a type marker and a nested text-data object; animated text documents may change as the playhead moves. That is why a global replacement across the JSON text is dangerous. The same word may appear in a layer name, image path, expression, font identifier and visible text with four different responsibilities.
The Lottie community specification describes a text layer’s t object, an animated text document under d, and keyframes under k. A text document’s fields can describe the displayed string, font selection, size, justification, tracking and other layout properties. Character shape data can be stored separately in a chars array. The fonts.list entries may point to system fonts or external font resources. These roles are connected: replacing the displayed string does not make a font capable of rendering its new characters.
A text-layer animation may also contain a path-following text arrangement, text animators and expression-driven values. A project that uses these features needs more than the generic advice “change t.” Some text is supplied through runtime properties or supported slots rather than static document text. A reviewer must identify where a string is truly authored and where it is calculated or supplied by the application. The repair may belong in the host application’s locale bundle rather than inside the animation file.
The format is not identical to every renderer’s feature set. Browser players, native mobile players and other libraries can differ in font loading, expression support, shaping and handling of newer properties. Passing an example in one viewer is not proof of portability. Before translation starts, record the player names and versions, target operating systems, expected font packaging and whether the animation is rendered as SVG, canvas or native drawing. Otherwise a team may approve a locale in an editor preview that users never see correctly.
Inventory text and distinguish it from identifiers
Open the animation as structured JSON and enumerate layers with text behavior. For each text document keyframe, record the original visible string, time, font reference, alignment, text box constraints and any expression or slot reference that could override the displayed content. Maintain stable references to the layer and keyframe. A useful inventory names a human purpose, such as opening instruction, countdown warning or confirmation, rather than only a numeric array index. The purpose helps translators preserve meaning even when an animation uses abbreviated copy.
Layer names are primarily authoring or debugging labels; they are not automatically user-facing. Asset IDs, precomposition references and transform parameters belong to the animation contract. A word such as Welcome could occur as the visible message and as a layer’s internal name. Translating the latter may break a tool that looks up layers by their names, even if Lottie’s core renderer does not use the name to draw the graphic. The safe default is to freeze identifiers and translate actual display strings only when the system owner has identified them as editable.
An animation may include text that has already been converted to vector outlines. In that case the visual letters are shapes, not an ordinary editable text document. A machine translation script cannot reliably discover or replace them by searching the JSON for an English phrase. The authoring source file may be needed to regenerate the animation. If only outlined geometry is available, the team should document that limitation and consider an external HTML text overlay or a rebuilt graphic rather than claim that every Lottie file is directly localizable.
Text embedded inside raster images is another distinct problem. An image asset can contain words that OCR sees visually but that the Lottie JSON represents only as pixels. The translation process might need access to the original layered design asset or a replacement image. Treat it as a separate media operation with its own evidence and QA. Do not patch arbitrary base64 content or file paths in the hope that visible words will change. The translation inventory should identify editable text, outlined text, rasterized text and runtime-injected text separately.
Freeze a structural baseline before changing a word
Save the original JSON and compute a checksum; capture its declared frame rate, in and out points, canvas dimensions, layer order, layer types, precomposition references and animation start times. These fields are not generally translatable. A source and target comparison can allow documented changes to text documents and perhaps reviewed formatting fields while requiring other values to remain unchanged. If the animation is used in a quiz, also record the frame at which an answer becomes available or an action is triggered.
The comparison should be structural rather than purely byte-for-byte, because JSON member order and whitespace are not typically semantically important. A canonicalized parse can compare objects while excluding only approved translation fields. At the same time, retain the raw before-and-after files, since a tool may remove fields it does not understand. A valid parser can quietly discard unfamiliar properties when serializing, and this can cause a visual defect even though the output is still valid JSON.
Document the allowed layout adjustments separately from immutable motion. A Chinese translation might need different line breaks or a font that covers additional glyphs. Changing a font or text box can be a valid localization adjustment, but it deserves explicit review rather than being hidden in the same diff as a string replacement. The QA record should say which formatting properties changed, why they changed and which renderers were tested. Such a record makes future revisions less likely to repeat an expensive investigation.
A disciplined process also keeps the original animation available for rollback. If a translated version performs poorly on an older mobile renderer, a release manager should be able to switch the affected locale back to an approved fallback without changing the application’s business logic. A checksum alone will not explain which locale was tested; associate each variant with a locale tag, a source animation revision and a small reproducible test set.
A small text-layer JSON fixture
The following shortened JSON is an illustrative text-layer fragment, not a full animation that can be played by itself. It demonstrates a text document under a text layer and two timed keyframes whose displayed words differ. The string inside each document is translatable; the time values and font reference must be interpreted in their animation context. A reviewer should not infer an exact number of seconds from t alone without the composition’s frame rate and timing rules.
{
"nm": "Lesson Prompt",
"ty": 5,
"t": {
"d": {
"k": [
{"t": 0, "s": {"t": "Read the question", "f": "SchoolSans-Regular", "s": 48, "j": 0}},
{"t": 36, "s": {"t": "Check the evidence", "f": "SchoolSans-Regular", "s": 48, "j": 0}}
]
}
}
}A localized candidate might replace those two visible sentences with two Chinese instructions, leaving the keyframe times at zero and thirty-six and preserving the font identifier only if the linked font supports the selected characters. If the font does not support them, the proposed output has a rendering defect even though the JSON patch follows the intended field path. The correct solution requires a reviewed font strategy, and possibly additional layout changes, before the candidate can be called acceptable.
This distinction illustrates why the data model and visual model need separate tests. A structural unit test can prove that only the text-document strings changed; a screenshot comparison can reveal missing glyphs, overlap and timing problems. A semantic reviewer can then check whether the second instruction is truly about examining evidence rather than merely checking that an answer exists. None of those checks subsumes the others. The same fixture should be rendered at each keyframe and at several points between them.
Translate the sequence, not just the isolated text strings
An animation is a tiny timed narrative. The first sentence may direct attention toward a diagram, the second may reveal a hint and the third may announce that an activity is complete. Text extracted into a flat spreadsheet loses the order, transitions and visual objects needed to interpret these messages. Provide translators with a storyboard showing relevant frames, the preceding and following captions and the intended action. This can prevent a fluent but wrong instruction from appearing at the moment when the learner is supposed to make a decision.
Timing can make ordinary grammar choices important. An English instruction might be short enough to read comfortably in one second; a target-language equivalent may need longer. The right solution is not always to remove meaning. A designer may shorten nearby visual copy, adjust the time available, break an instruction into two stages or create a separate accessible transcript. If the animation’s timing drives an interactive question, any such adjustment needs interaction testing because moving a visual message without moving the answer trigger can create unfair or confusing behavior.
The translation memory should preserve context. A phrase such as “Try again” might be encouragement after a harmless pronunciation attempt, or it might appear after a failed submission whose answer has been consumed. Those are different states. The localized sentence must not promise another attempt when the application will not allow it. Review the full user journey, including how a learner enters and exits the animation, what is clickable while it plays and which system state the animation represents.
Where an animation communicates a safety instruction or a financial action, never rely on animation alone. Supply equivalent accessible text outside the moving graphic and ensure a user can pause or review essential instructions. The translation’s job is to preserve what action is required, not to maintain an exact word count. A caption can be concise and still complete if the host interface provides supporting content, but the supporting content must be present in every locale where that choice is made.
Font coverage and glyph shaping are part of localization
A font name in a JSON file does not guarantee the glyphs needed by the target language exist on the user’s device. CJK ideographs, Indic scripts and combining marks can expose gaps that English-only tests never encounter. A viewer may substitute a fallback font, render empty boxes or misplace marks. Embedded character shapes, where used, may cover only the characters present in the original English animation. Adding a target-language sentence then requires fresh character assets or a compatible text-rendering mode.
Test an entire sentence containing the actual script, not just a language name. The visual reviewer should check baseline alignment, ligatures, consonant clusters, punctuation and numerals. A script that combines glyphs differently may need more horizontal or vertical room even with the same apparent number of characters. Text may also be rotated or animated along a path, where shaping defects become more visible. Inspect at normal playback speed and also at a paused high-resolution frame, because a brief animation can hide a glitch during casual viewing.
Font licensing and packaging matter as well. A font downloaded from a URL in a desktop preview may be blocked in an offline mobile application or by a production content security policy. A localization team should not assume it can embed a commercial font simply because it appeared in an authoring project. Identify fonts permitted for each distribution channel, include appropriate assets where authorized, and use a fallback with verified script coverage. Check whether the player honors the specified font reference and how it behaves when the requested resource fails to load.
When text is converted to outlines, a renderer may no longer perform dynamic shaping at all. The outlines encode particular glyph shapes. Translating via replacement outlines changes the graphic asset, and the process must be repeated for each new string or language. That strategy can produce faithful visual design for a fixed title, but it becomes costly for a dynamic notification or a product with many locales. Choose the representation based on whether the copy is stable, how many languages are supported and whether accessibility requires real selectable text.
The hidden complexity of line wrapping and alignment
The same translated phrase can fit in a static desktop screenshot and fail during animation. A layer may scale down, rotate or slide across another shape; text can look correct at its initial position yet collide with a character illustration halfway through. Define test frames at the beginning, at every text change, near maximum scaling and at the final visible moment. A screenshot comparison should highlight not only visual changes but whether the content remains readable in its intended duration.
Line breaks are not purely aesthetic. If a phrase is split at an unnatural point, readers may temporarily interpret the first line as a complete command. In languages with complex word order, the second line can change the meaning of the first. A localized break should be reviewed as typography and language together. Some players use text box settings; others render manual breaks. Ensure that the chosen mechanism is actually supported in the deployment player and that editing a line break does not produce an unintended escape sequence in JSON.
Right-to-left content needs particular care. A text layer’s alignment or justification value may not correspond to the direction in which the target script should be read, and visual markers can move unexpectedly when punctuation or numbers are present. Verify mixed-direction examples, especially when an Arabic instruction contains a Latin classroom code or a numerical value. Do not assume that reversing the glyph order manually is a valid repair; let a renderer with proper bidirectional text handling produce the display where supported.
A responsive application may show the same Lottie in several containers. If the animation scales to fill a narrow mobile card, its text may become too small even without clipping. The product team should decide whether to use an alternative mobile animation, external responsive text or a minimum container size. A localization QA report should name the tested device widths and accessibility zoom levels rather than simply state that the output “looks good” on the designer’s laptop.
Failure mode: translating internal layer names breaks tooling
A translator sees nm: "Lesson Prompt" and changes it to a target-language phrase. The animation may continue to render, so the edit looks harmless. Later, a script or editing tool that locates layers by their original names cannot find the expected object. The problem is that an authoring label was mistaken for visible copy. The diagnostic is to search every changed JSON path and compare it with the translation inventory’s classification of source fields.
The repair is to restore the stable layer name unless the project explicitly supports localized authoring names. Keep the target language in text-document fields or host-level resources. If a tool genuinely uses localized names, define its lookup contract separately and test it. Broadly translating every human-readable JSON string is not a defensible policy because readability does not establish that a field is safe to change.
Failure mode: replacing the first keyframe leaves the old language later
A localization script replaces the first occurrence of “Read the question” but ignores a later keyframe that restores the English text. The animation seems translated at its opening, then unexpectedly switches languages mid-playback. The diagnostic is to enumerate all text document keyframes and render the entire timeline, not just the first frame. Search every visible string against a source-language inventory and flag those that require explicit retention or translation.
Repair the whole intended text sequence while preserving keyframe times unless a separate timing change is approved. A completion test should play the animation through looping behavior as well as a single pass. Some animations include ending keyframes or hidden precompositions that appear only under particular application states. These must be inspected in the actual application path rather than assumed absent from a short preview.
Failure mode: translated glyphs are missing from embedded character data
An English animation uses vector glyphs for every letter in its original text. A new target string contains characters absent from the chars collection. Depending on the renderer, the result may contain missing shapes or fallback behavior that differs across platforms. The JSON may be syntactically valid and structurally unchanged apart from text, which makes this defect easy to miss in automated tests. Render exact target strings on every player and deliberately include rare characters used by the product.
The repair may require changing the font strategy, adding character outlines through the authoring pipeline or moving localized text outside the Lottie into the host UI. Do not insert arbitrary character records without understanding how their shapes and widths are represented. An authored asset should be regenerated and checked where the format’s dependencies are complex. Track the resulting asset revision so that a later copy edit triggers the necessary glyph rebuild rather than silently removing coverage.
Failure mode: a text change alters an interactive instruction
A feedback animation appears when a student submits an answer. The English text says “Review the explanation before retrying,” but the target string is shortened to “Try again.” The student now receives a different instruction and may skip the required explanation. This is a semantic failure even if the animation looks beautiful. The diagnostic is to compare the translated message with the actual application state and ask a bilingual reviewer what action a learner would take from that message alone.
Repair the meaning before adjusting typography. If space is insufficient, redesign the sequence: show a shorter first prompt followed by the explanation instruction, add a companion accessible text block or lengthen the time the message remains visible when the interaction design permits it. The acceptance test is behavior: learners in the target locale understand the same next step as learners in the source locale.
Failure mode: renderer differences make QA deceptively green
A designer tests the animation in a browser preview with an available system font. The shipped mobile app uses a different renderer and font-loading strategy. The target-language text disappears or loses complex shaping on only one platform. The diagnostic is a matrix of target locale, renderer version, operating system, font load mode and keyframe. A single generic “Lottie supported” field is not enough to predict behavior across these combinations.
The repair depends on the mismatch. It may involve bundling an allowed font, replacing an unsupported feature, regenerating the animation or presenting text as native UI instead of a Lottie layer. Keep a small golden animation for every script family used by the product, with known sentences and screenshots. Run it after player updates; dependency upgrades can break localized rendering even when the translation files are unchanged.
Failure mode: escaped characters change what the viewer displays
JSON strings use escape sequences for quotation marks, backslashes and certain control characters. A translator may paste an unescaped quote or insert a literal line break in a context where the serializer expects \n. The resulting file may not parse, or a well-meaning tool may double-escape the sequence and display the characters backslash and n rather than a new line. The diagnostic is to parse the produced JSON and compare rendered text with intended code points, not just with raw source bytes.
Use a serializer for JSON rather than hand-building strings through concatenation. Keep Unicode handling explicit and test punctuation likely to occur in instructional text. A successful parse is only the first step; inspect the actual glyph sequence at runtime. This is particularly important when a localized string includes quotes around a learner’s answer, escape-sensitive examples or bidirectional punctuation.
Build a two-part validator
The structural validator should parse both source and candidate JSON, locate approved text-document paths and compare the rest of the data under a recorded allowlist. If changes to alignment or fonts are approved, list them individually with reviewer notes. It should check that frame rates, composition bounds, layer types, image references and timing fields have not changed unexpectedly. It should enumerate all target strings and require an explicit decision for each: translated, deliberately retained, rendered externally or blocked pending a new source asset.
The visual validator should play or render the animation in target players at selected frames and viewports. Capture opening instructions, every keyframe boundary, extremes of scaling or rotation and the ending state. Compare positions and readability rather than relying on pixel equality, since legitimate glyph changes make strict image matching unsuitable. Include glyph coverage, line breaks, contrast, language direction, accessible alternate text and the action implied by each message. A reviewer should be able to point to a screenshot and explain why a deviation is acceptable.
A small traceability table can connect the two. Each translation entry can record layer path, keyframe time, source copy, target copy, locale, reviewer, font strategy and screenshots. If a later bug report cites a missing prompt, the team can locate its JSON path and replay exactly the frame where it should appear. Without this record, a developer may search for the literal English words in source files, find none, and incorrectly conclude that the report is outdated.
Do not treat screen-reader accessibility as guaranteed because visible text is present in the animation. Many Lottie renderers draw graphics without exposing each internal text layer as meaningful document text to assistive technology. The host application should provide a synchronized or equivalent accessible instruction, and that instruction needs the same translation and semantic QA as the animation. For timed instructions, ensure a learner can recover the information rather than lose it permanently when the motion ends.
Changed-context transfer exercise: a museum safety animation
A museum has a short Lottie animation with three messages: “Follow the blue path,” “Do not touch the exhibit,” and “Ask a guide if you need help.” The translated version will be shown in a right-to-left language on both an information kiosk and a mobile browser. A designer discovers that the second instruction is an outlined shape rather than a text document; the first appears in two text keyframes, and the third uses a font that lacks target-script glyphs. Decide what can be edited directly and what requires redesign.
The answer separates field types. Translate the first instruction at both intended document keyframes and verify timing and direction. The outlined second instruction cannot be reliably changed as JSON text, so obtain the authoring source and regenerate it, or replace it with a supported external text layer. The third needs a target-script-capable font or native host text. In each case, preserve the animation’s underlying action meanings and do not translate layer identifiers that automation might rely on.
A passing test shows each instruction in context, including the moving path illustration and any arrows that might imply direction. It also checks the mobile viewport, kiosk player, final frame and assistive-text equivalent. A particularly important semantic test asks a visitor whether the translated message prohibits touching the exhibit or merely suggests avoiding contact. The museum should resolve that distinction before approval because an attractive animation is not adequate evidence that a safety instruction was understood.
Practical review checklist
- Record source animation revision and target renderer versions.
- Enumerate all true text layers, document keyframes, font assets and runtime-injected text.
- Keep layer identifiers, timing, composition structure and asset references frozen by default.
- Translate approved visible copy in its storyboard and interaction context.
- Identify outlined and rasterized text that cannot be edited as normal strings.
- Check target glyph coverage and lawful font packaging.
- Render every keyframe, scaling extreme, loop and viewport used by the product.
- Verify right-to-left or complex-script shaping where applicable.
- Provide accessible equivalent text outside the animation when necessary.
- Save a machine diff, screenshots, reviewer decisions and reversible locale artifact.
Limits and boundaries
A successful JSON parse does not establish full Lottie specification compliance or prove support across all renderers. Feature support, expressions, font availability and mobile behavior vary. This article’s fragment is a teaching fixture, not a complete playback file or an assertion that a particular vendor will interpret every optional property in the same way. Production validation must include the actual animation file and its runtime integrations. Some text should be localized at the host application layer rather than inside Lottie.
Machine translation can produce useful initial suggestions, but short animated messages are unusually sensitive to timing, instruction semantics and visual context. A target phrase that is fluent on paper may be impossible to read in its allotted duration. The right remedy may be editorial condensation, a longer hold, a restructured animation or a static accessible alternative. Those are product decisions that require user testing, not just string validation.
Summary: make text editable without making motion fragile
The reliable way to localize Lottie is to see it as a timed structured graphic rather than a bag of strings. Find the actual text documents, freeze machine identities and motion, translate the full instructional sequence, and verify glyphs, keyframes and actions in real players. When an animation has outlined words or inaccessible timing, do not conceal the limitation. Use the authoring source or host UI to create a genuinely usable language experience that preserves the original intent.
Plan a multilingual release without multiplying hidden asset risks
An animation released in six languages is not merely one source file plus six interchangeable text bundles. Some locales may require different fonts, altered breaks or a separate accessible text component. Build a variant register with source animation revision, target locale, visual asset checksum, player version, expected font package and screenshots of critical moments. This register lets a developer detect an outdated locale after a designer adjusts the source animation’s timing. A missing locale should resolve to a deliberate, reviewed fallback rather than to an older animation that has different instructions or actions.
The design team should decide which changes require all translations to be reviewed again. A color adjustment in a decorative shape may not affect message meaning, but moving a visual arrow next to a negation word might. Changing the moment at which a button becomes active can make an instruction misleading. Adding a third keyframe can introduce new copy absent from previous locales. Treat the animation as a small product with versioned content dependencies, not as an isolated promotional graphic that can be copied blindly between projects.
A useful release test uses a matrix of language and interface state. For a classroom quiz animation, test a correct answer, incorrect answer, timeout and activity restart, then render the intended text in each state. A sentence that appears only when the answer is wrong may be overlooked during the happy-path preview. Record whether a long translation changes the time required to understand the next step. This approach prevents teams from approving a locale based on the easiest single-frame screenshot while missing defects in the contexts where learners most need help.
Finally, arrange a fallback that preserves functionality when animation delivery fails altogether. A loading error should not prevent a learner from reading an essential instruction or accessing a retry control. Native UI text can show the message while a decorative animation is unavailable. Localize and test that fallback through the same semantic review as the animation copy, and ensure it refers to the current state rather than an outdated motion sequence. This keeps accessibility, resilience and multilingual support aligned with the same educational task.
A release gate should also distinguish decorative variation from semantic variation. An animation of a book opening can be translated differently to match a culture’s visual expectations without changing a task, but a warning icon moving from a prohibited object to a permitted one changes the instruction. A reviewer should write one sentence describing the operational consequence of each animated prompt and compare that sentence across locales. If the consequences differ, pause the release and inspect copy, illustration and timing together. A text-only review can miss the visual contradiction; a screenshot-only review can miss a mistranslated conditional instruction. Requiring both perspectives is a practical safeguard for educational animations used by learners who may not yet read the interface language fluently.
Frequently asked questions
Can I translate every readable string in a Lottie JSON file?
No. Some strings are internal layer names, asset references or expressions. Only fields identified as translatable display text should be changed as a routine localization task.
Where does Lottie usually store text-layer copy?
Text layers can contain text document data under a t object, with document keyframes under d.k. The specific animation and renderer must be inspected because other mechanisms also exist.
Does changing JSON text preserve animation timing?
It can if only approved text fields change, but longer words may be unreadable within the original duration. Both structural comparison and visual timing tests are necessary.
What happens when letters were converted to outlines?
The letters are graphic shapes rather than editable text. A source-authoring rebuild or another supported text overlay is usually needed.
Are CJK and Indic scripts always supported by the original font?
No. Verify glyph coverage, shaping and font loading on target players. A font name alone does not guarantee correct rendering.
Can a Lottie animation provide screen-reader instructions automatically?
Do not assume so. The host application often needs accessible equivalent text and controls, with their own localization QA.
Why must every text keyframe be checked?
An animation may change its message over time, restore an earlier phrase or reveal a hidden text layer. Checking only the first frame can miss untranslated copy.
Is a translated layer name harmless if the animation still plays?
Not necessarily. External tooling and application code may look up layers by name, so default to preserving such identifiers.
What is the most important visual test?
Render the actual target string at key transitions and constrained viewport sizes, and verify that it remains readable long enough and still tells the user the intended next action.
Can an automatic translation tool fully validate Lottie localization?
No. It can assist with extraction and structural checks, but semantic decisions, script rendering and product behavior require human and runtime testing.
Authoritative sources
- Lottie community specification: text data, fonts and keyframes — structure of editable text layers.
- LottieFiles documentation: Lottie JSON format — animation capabilities and limitations.
- Lottie community documentation: animation and layers — layer types and animation context.