Yarn Spinner Localization: Line IDs, CSV and Voice QA

How do you translate and localize Yarn Spinner projects professionally without breaking the experience? This complete Yarn Spinner localization guide explains the actual text and language mechanisms, how to make the interface understandable across countries, and how to test the final release. It is written for narrative designers, Unity developers, interactive-fiction teams, voice directors and localization specialists working on choice-driven dialogue. You can follow the decisions in order and use the troubleshooting section when a real game behaves differently from its translated source files.

The essential platform distinction is this: Yarn Spinner identifies lines with tags such as #line:a1b2c3d and can export translation strings as CSV. In Unity projects its built-in localization or Unity Localization integration associates those line identities with translated text and possibly audio assets. A working language file is only one part of a usable product. A player has to see the correct message, understand the available action, and receive the intended result. Before committing to several languages, confirm the toolchain and release format for the version of Yarn Spinner your project actually uses.

This guide follows a branching railway-station story where a lost traveller asks for directions, chooses a ticket, changes platforms and eventually receives a spoken departure announcement. It covers translation scope, text identities, interface wording, language selection, content revisions, real-player testing and delivery checks. The practical objective is do not translate line IDs, variable names, branching commands, locks or file references as though they were ordinary prose; translations must still lead to the same dialogue and game outcomes. You will also find a four-week rollout, a symptom-first fault finder and frequently asked questions for teams preparing their first multilingual edition.

Quick answer: the reliable localization route

Identify the player-visible content and all non-translatable program identifiers in Yarn Spinner.
Create stable source references and give translators scene, speaker and decision context.
Translate complete meanings, not disconnected words; protect variables, logic, format markers and resource keys.
Test each choice and message in the actual running product in a supported target language.
Package the complete release and keep evidence of source version, language coverage, fallback and player outcomes.

Contents and how to use this guide

What a translated game must preserve
A worked story and the language-versus-logic boundary
Twenty-five practical decisions from source preparation to distribution
A symptom-first troubleshooting reference
Three complete player journeys and a testing matrix
A four-week plan, reader questions and primary documentation

Yarn Spinner: what language changes and what must remain the same

In our running example, a branching railway-station story where a lost traveller asks for directions, chooses a ticket, changes platforms and eventually receives a spoken departure announcement. A translator is not merely replacing captions. The words must give the player enough information to decide what to do next, but not more information than the original game intended. A menu term, a puzzle clue and a conditional response may all need different review methods, even if they share a word in English.

Consider this specific source moment: The source line ‘Rosa: The lamp has been out for days. #line:a1b2c3d’ has a stable identity independent of its Spanish or Japanese wording. That identity should also connect approved voice audio to the right moment. This demonstrates the core boundary: language communicates a decision while program state controls its consequences. If you preserve only the visible words, readers may receive natural prose that leads to a wrong outcome. If you preserve only code, they may receive an accurate branch with an incomprehensible choice. Both must agree.

A useful small-scale trial is one route through the game: first launch, language selection, an instruction, a decision, a state change, a surprising result, recovery and a saved-session return. Choose one target language with a competent human reviewer. Keep the source-language journey beside it. A successful comparison is not identical sentence length; it is equivalent information, choice and outcome.

Yarn Spinner localization: twenty-five implementation decisions

1. Start with a branch map rather than a word list

Dialogue is not a spreadsheet of unrelated sentences. Each line belongs to a state where the player knows something, can choose a response or may have triggered a variable.

For a practical first pass, Draw the main conversation routes and annotate who speaks, which conditions are active and how each choice changes the scene. Attach that map to the translation package. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

A polished answer can be nonsensical when displayed before the character learns the relevant fact. Test translations in the real branch, not only as isolated CSV rows. The editorial review should ask what a reader will infer at precisely this moment. Check the surrounding scene and whether the text introduces a new fact or a new obligation. A translation that reads smoothly in isolation can still give the wrong instruction during play.

2. Add stable line tags before translation

Yarn Spinner can generate a line ID from location when no explicit tag exists; that identity can change as scripts are edited. Stable #line tags support durable translations.

On a small project, Use the current Yarn Project Inspector’s Add Line Tags to Yarn Scripts workflow where supported; keep identifiers unique and place them under version control. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

If a script edit changes automatic IDs, translations and voice clips may stop matching. Do not export a production CSV until the line identity policy is settled. Check the full path from source data through language selection to the running interface. A file may contain the right phrase while a cache, scene property or compiled artifact continues to display an older version. Name the exact location and build when reporting a discrepancy.

3. Treat line IDs as permanent addresses

The line tag is a reference used by the Dialogue Runner and localizations. Its literal spelling is generally not displayed to players and should not be translated.

To make this operational, Record a unique ID for each spoken line and option. If a sentence moves to a different node, preserve the existing identity when its meaning remains the same. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

Accidentally duplicating a tag can attach the wrong text or asset. Validate uniqueness across all scripts rather than per file. Treat author intent and player behavior as separate checks. The original author should confirm the meaning, while a target-language reader should explain what action they expect to take. Agreement between those two observations is stronger evidence than a word-for-word comparison.

4. Export a translator-friendly CSV

The Yarn Project’s export creates text records plus metadata that can help a translator understand origin and sequence. Additional columns may carry identifiers and source-change indicators.

In the working story, Keep an untouched export as the source baseline; add separate target-language copies and supply scene screenshots, speaker notes and character glossary. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

Translators should not reorder or rename structural columns to suit a spreadsheet. Test CSV parsing after every round trip from office software. When several languages are supported, repeat the same state and control sequence in each one. A translation should not change hidden game values or which choices are available. If the text is deliberately adapted, record why the player’s understanding remains equivalent.

5. Preserve id and lock columns

Yarn Spinner’s documentation specifically warns translators not to change IDs or locks. The lock helps detect source changes, while the ID connects the translated row to runtime content.

For a practical first pass, Protect those columns in the handoff file or validate them in a script after import. Ask reviewers to edit the text column and designated translation notes only. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

Changing a lock can hide a source revision or raise false warnings; changing an ID can orphan a translation. Treat any unexpected difference as a blocking data defect. The editorial review should ask what a reader will infer at precisely this moment. Check the surrounding scene and whether the text introduces a new fact or a new obligation. A translation that reads smoothly in isolation can still give the wrong instruction during play.

6. Distinguish speaker label from dialogue text

A CSV row may begin with a character name and colon. The speaker label is part of presentation and may be adapted, but must remain recognizable to the line processor.

On a small project, Publish a proper-name policy and test the parser with translated or transliterated speaker names where allowed. Keep character identity separate from local nickname choices. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

Deleting a required name separator or accidentally translating a machine-readable key can shift rendering. Check the final speaker portrait and text bubble together. Check the full path from source data through language selection to the running interface. A file may contain the right phrase while a cache, scene property or compiled artifact continues to display an older version. Name the exact location and build when reporting a discrepancy.

7. Translate player options for decisions

An option is a promise about what happens after clicking it. A too-soft or too-strong verb changes perceived consent and can make a branching game unfair.

To make this operational, For every choice, describe the subsequent action and consequences in plain language. Let translators compare the text with the resulting state transition. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

A player who chooses ‘Ask politely’ must not unexpectedly trigger a threatening response because the translated option changed the intended act. Treat author intent and player behavior as separate checks. The original author should confirm the meaning, while a target-language reader should explain what action they expect to take. Agreement between those two observations is stronger evidence than a word-for-word comparison.

8. Preserve inline placeholders

Yarn Spinner can export inline expressions as placeholders such as {0} and {1}. Those markers are data positions, not normal words.

In the working story, Create source and target tests for all placeholder-bearing lines; allow grammatical reordering only where the line formatter supports it. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

If placeholders disappear, show in the wrong order or display raw braces, review the format and the runtime variable values before changing the story. When several languages are supported, repeat the same state and control sequence in each one. A translation should not change hidden game values or which choices are available. If the text is deliberately adapted, record why the player’s understanding remains equivalent.

9. Plan for plurals and grammatical gender

Languages differ in plural categories, agreement and word order. Replacing an English plural with one alternate suffix is not a world-facing solution.

For a practical first pass, Use the supported markup and language-aware formatting available in the Yarn Spinner version being shipped; test zero, one, two and larger counts. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

Do not copy obsolete markup syntax from older documentation without checking the current runtime. A valid English format may not capture another language’s grammar. The editorial review should ask what a reader will infer at precisely this moment. Check the surrounding scene and whether the text introduces a new fact or a new obligation. A translation that reads smoothly in isolation can still give the wrong instruction during play.

10. Choose one primary localization integration

Yarn Spinner offers a built-in localization workflow and integration with Unity’s Localization package. They are alternatives with different asset and table management.

On a small project, For a small team choose the simpler route that meets real requirements; for an existing Unity Localization project connect the Yarn line provider to its String Table Collection. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

Running two uncoordinated sources of truth can create divergent dialogue text. Document which system owns each language table and which updates are allowed. Check the full path from source data through language selection to the running interface. A file may contain the right phrase while a cache, scene property or compiled artifact continues to display an older version. Name the exact location and build when reporting a discrepancy.

11. Import language CSVs into the Yarn Project

In the built-in approach, the project associates a selected language with its translated strings file. Merely placing a CSV in Assets does not complete runtime wiring.

To make this operational, Set the language entry, attach the correct strings file and apply changes. Verify that a line with a known unique ID renders in the requested target language. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

Do not mistake an import warning for an optional cosmetic issue. A missing or unreadable file may leave an edition unavailable. Treat author intent and player behavior as separate checks. The original author should confirm the meaning, while a target-language reader should explain what action they expect to take. Agreement between those two observations is stronger evidence than a word-for-word comparison.

12. Keep base-language source authoritative

The base text comes from Yarn Scripts. Under Unity Localization integration, the base-language string table can be regenerated from those scripts.

In the working story, Edit original narrative lines in Yarn, not in a generated base-language table. Have translators maintain other language columns through their designated workflow. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

Manually fixing the generated base column can disappear at the next import. Confirm where the source of truth lives before assigning editing permissions. When several languages are supported, repeat the same state and control sequence in each one. A translation should not change hidden game values or which choices are available. If the text is deliberately adapted, record why the player’s understanding remains equivalent.

13. Connect the Dialogue Runner’s line provider

A localized string table does not guarantee the runner uses it. The Dialogue Runner’s provider selects localized text and optionally assets for the current locale.

For a practical first pass, Inspect the runner and test a line that has visibly different text in a second locale. For Unity Localization, configure the Unity Localised Line Provider with the correct table collection. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

If text stays in the base language, investigate provider wiring and locale selection before asking the translator to redo a correct CSV. The editorial review should ask what a reader will infer at precisely this moment. Check the surrounding scene and whether the text introduces a new fact or a new obligation. A translation that reads smoothly in isolation can still give the wrong instruction during play.

14. Tie voice files to line identity

A voice clip can be associated with the same line ID as the translated sentence. Asset folders or tables must match the chosen localization integration.

On a small project, Name voice assets systematically, record the speaker and language, and test a playback route that includes interruptions and repeated lines. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

An audio clip in the wrong language can be worse than no clip. Report text and voice coverage separately and use intentional fallback when an approved recording is missing. Check the full path from source data through language selection to the running interface. A file may contain the right phrase while a cache, scene property or compiled artifact continues to display an older version. Name the exact location and build when reporting a discrepancy.

15. Keep localization and game logic separate

Yarn commands and variables decide dialogue flow; localized text explains the player’s situation. Turning display text into a variable key makes translations brittle.

To make this operational, Keep branch conditions bound to stable game state and use line IDs for text resources. Run the same choice path in two languages and compare outcomes. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

When a translated answer changes which branch executes, inspect the logic-to-text boundary rather than blaming word order alone. Treat author intent and player behavior as separate checks. The original author should confirm the meaning, while a target-language reader should explain what action they expect to take. Agreement between those two observations is stronger evidence than a word-for-word comparison.

16. Offer a safe language switch

Some games change locale at the title screen; others allow it during dialogue. The experience must be consistent and avoid stale already-rendered lines.

In the working story, Define whether switching refreshes the current bubble, the next line or the whole scene; tell the player what to expect and test save/resume. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

A mixed-language bubble and voice clip after switching is an observable defect. Define a precise acceptance result for the transition. When several languages are supported, repeat the same state and control sequence in each one. A translation should not change hidden game values or which choices are available. If the text is deliberately adapted, record why the player’s understanding remains equivalent.

17. Plan fallback by message ID

Missing target-language lines should be visible in QA, not silently counted as translated. A usable player experience still needs a readable default.

For a practical first pass, Measure coverage from resolved line IDs and flag missing rows. Distinguish lines not yet reachable in a playthrough from lines missing altogether. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

Do not report a language as complete based on a percentage of exported rows when important ending choices remain untranslated. The editorial review should ask what a reader will infer at precisely this moment. Check the surrounding scene and whether the text introduces a new fact or a new obligation. A translation that reads smoothly in isolation can still give the wrong instruction during play.

18. Review right-to-left and non-Latin UI

The Yarn text may be correct while a Unity text component renders digits, punctuation or mixed-script names badly.

On a small project, Test actual target text in the game’s chosen font, dialogue box, choice button and accessibility layout. Include line wraps and long proper names. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

A valid CSV cannot guarantee shaping, contrast or reading order. Verify what the player actually sees on the supported platforms. Check the full path from source data through language selection to the running interface. A file may contain the right phrase while a cache, scene property or compiled artifact continues to display an older version. Name the exact location and build when reporting a discrepancy.

19. Test branch coverage beyond the opening scene

Narrative games may include dozens of mutually exclusive routes. A simple start-to-finish test exercises only a fraction of the localized content.

To make this operational, Build a branch matrix with at least one path through each major decision, an error recovery, a save restoration and every ending category. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

Do not certify all choices because the first conversation looked good. Record the exact route and locale tested so missed branches are visible. Treat author intent and player behavior as separate checks. The original author should confirm the meaning, while a target-language reader should explain what action they expect to take. Agreement between those two observations is stronger evidence than a word-for-word comparison.

20. Manage source revisions with lock checks

New scenes and changed lines must be refreshed into the translation handoff. An unchanged ID does not mean the English meaning remained identical.

In the working story, Export after an approved narrative revision, compare locks and source text, and request targeted retranslation for semantically changed lines. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

Old approved words should not silently survive a newly different source line. Review consequences as well as textual differences. When several languages are supported, repeat the same state and control sequence in each one. A translation should not change hidden game values or which choices are available. If the text is deliberately adapted, record why the player’s understanding remains equivalent.

21. Handle embedded variables and formatting errors

A line may be syntactically valid in CSV but invalid when the game substitutes live values. The only reliable test uses real runtime states.

For a practical first pass, Exercise empty names, punctuation-rich names, singular counts, negative values and very large values in the dialogue UI. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

If a broken formatter appears only at one quantity, fix the markup or placeholder logic and add that boundary to regression tests. The editorial review should ask what a reader will infer at precisely this moment. Check the surrounding scene and whether the text introduces a new fact or a new obligation. A translation that reads smoothly in isolation can still give the wrong instruction during play.

22. Respect editorial tone across paths

Characters may sound different in anger, fear or relief. A phrase should not be translated in isolation from the relationship established by earlier choices.

On a small project, Create a voice guide for each character with approved honorifics, humour, formality and prohibited spoilers. Have readers examine contrasting routes. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

A globally consistent glossary is useful but cannot replace dramatic context. Reconsider terms when the same source word serves a new narrative purpose. Check the full path from source data through language selection to the running interface. A file may contain the right phrase while a cache, scene property or compiled artifact continues to display an older version. Name the exact location and build when reporting a discrepancy.

23. Validate build packaging

Editor tests can find localized CSVs from the project tree even when the exported player lacks a needed asset or table.

To make this operational, Test a clean player build, language menu, first dialogue, voice clips, subtitles and a late-game choice without editor resources available. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

If an asset works only in development, fix build inclusion or addressing. Retest the final distributable rather than an intermediate bundle. Treat author intent and player behavior as separate checks. The original author should confirm the meaning, while a target-language reader should explain what action they expect to take. Agreement between those two observations is stronger evidence than a word-for-word comparison.

24. Prepare accessible text and voice alternatives

Some players need larger captions, no audio, slower reading or a screen-reader-compatible transcript. Localization makes these requirements more visible.

In the working story, Measure whether captions stay on screen long enough and whether choice controls expose readable labels at all tested languages. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

A language is not usable if text disappears before it can be read, especially when the only clue is delivered by audio. When several languages are supported, repeat the same state and control sequence in each one. A translation should not change hidden game values or which choices are available. If the text is deliberately adapted, record why the player’s understanding remains equivalent.

25. Record release evidence per language

Publishing should be based on an identified source commit, strings export, target CSV, localization configuration and tested binary.

For a practical first pass, Archive evidence for a complete player journey, count and mark fallbacks and keep reviewer sign-offs specific to each advertised locale. Start with one identifiable screen, scene, file or dialogue line rather than changing the entire project. Keep a short record of the input, the selected language, the expected player response and the result you actually observed. This creates a reproducible test of the decision rather than a subjective impression that the words sound good.

A generic ‘all languages done’ note is difficult to debug. A line ID, branch name and build number make later repair substantially faster. The editorial review should ask what a reader will infer at precisely this moment. Check the surrounding scene and whether the text introduces a new fact or a new obligation. A translation that reads smoothly in isolation can still give the wrong instruction during play.

A practical review of three complete player journeys

1. The first five minutes

Open a clean build of the Yarn Spinner project with no saved preferences. Invite someone who reads the target language but does not know the game’s source dialogue. Ask them to select a language, interpret the opening instruction, navigate the first choice and describe what they believe just happened. Observe hesitation rather than correcting it. Record the wording, the corresponding program state and whether the player reached the intended destination. If the test fails, distinguish an inaccurate sentence from an inaccessible control or missing language resource.

Pass when the reader can identify the language, perform the first meaningful task, understand the result and return to the menu without coaching. Keep the exact steps, language, expected action, screenshot or excerpt, and source revision in the review record so another tester can reproduce the journey.

2. A consequential decision

Use the central decision in a branching railway-station story where a lost traveller asks for directions, chooses a ticket, changes platforms and eventually receives a spoken departure announcement. Create two controlled test states that differ in one relevant flag or variable. In the source and target languages, present the same available options and ask the reviewer to predict the consequences before choosing. Then execute the action and compare branch destinations, values, explanations and later references. Review whether any option sounds mandatory when it is actually tentative, or harmless when it carries a cost.

Pass when the translated choice communicates the same commitment and the same intended state transition, even where sentence structure is different. Keep the exact steps, language, expected action, screenshot or excerpt, and source revision in the review record so another tester can reproduce the journey.

3. Failure, recovery and returning later

Begin from a previously saved session shortly before an error or blocked action. Resume in the target language, read the warning, take a recovery route and complete the next scene. Where the design permits language switching, repeat the transition once during the same session and look for stale captions, audio or labels. Finally reinstall or reload the distributed build in a clean profile to verify assets do not depend on an editor-only path.

Pass when the player recovers without losing the intended state, can interpret every critical warning and sees the promised language in the actual release. Keep the exact steps, language, expected action, screenshot or excerpt, and source revision in the review record so another tester can reproduce the journey.

Yarn Spinner troubleshooting: symptoms, causes, repairs and proof

1. Translations vanished after dialogue edit

An automatically derived line identity may have changed. Start by checking the actual user-facing state and locating the last point where the correct translation or correct branch was observed. This distinction matters because a linguistically sound target sentence may not have been selected by the runtime at all.

Inspect explicit #line tags and compare old and new exported IDs; restore a stable identifier where meaning is unchanged. Reopen the affected branch and check one previously approved line. Record the precise locale, screen or story position, build identity and whether the defect reproduces after a clean start. A correction is accepted only when the relevant player action works, not merely when an editor warning disappears.

2. CSV imports but displayed text is wrong

The ID column or line association may have been altered during spreadsheet editing. Start by checking the actual user-facing state and locating the last point where the correct translation or correct branch was observed. This distinction matters because a linguistically sound target sentence may not have been selected by the runtime at all.

Diff IDs against the baseline export and restore structural columns. Test a unique spoken line by its exact identity. Record the precise locale, screen or story position, build identity and whether the defect reproduces after a clean start. A correction is accepted only when the relevant player action works, not merely when an editor warning disappears.

3. Source change did not trigger review

The lock column may have been edited, hidden or ignored. Start by checking the actual user-facing state and locating the last point where the correct translation or correct branch was observed. This distinction matters because a linguistically sound target sentence may not have been selected by the runtime at all.

Compare source and target locks, then send changed lines for renewed linguistic approval. Verify the corrected line in a built conversation. Record the precise locale, screen or story position, build identity and whether the defect reproduces after a clean start. A correction is accepted only when the relevant player action works, not merely when an editor warning disappears.

4. A character name disappears

The CSV speaker prefix or delimiter was damaged. Start by checking the actual user-facing state and locating the last point where the correct translation or correct branch was observed. This distinction matters because a linguistically sound target sentence may not have been selected by the runtime at all.

Review required name-plus-colon handling in the current version and restore the expected format. Check both portrait and speaker caption while the line plays. Record the precise locale, screen or story position, build identity and whether the defect reproduces after a clean start. A correction is accepted only when the relevant player action works, not merely when an editor warning disappears.

5. English audio plays over another language

The asset provider selected an incorrect language or fallback. Start by checking the actual user-facing state and locating the last point where the correct translation or correct branch was observed. This distinction matters because a linguistically sound target sentence may not have been selected by the runtime at all.

Inspect audio folder or Asset Table associations for the line ID. Re-run the conversation, including interruptions, with the intended locale. Record the precise locale, screen or story position, build identity and whether the defect reproduces after a clean start. A correction is accepted only when the relevant player action works, not merely when an editor warning disappears.

6. Unity String Table shows text but Yarn does not

The Dialogue Runner may not have the correct localized line provider. Start by checking the actual user-facing state and locating the last point where the correct translation or correct branch was observed. This distinction matters because a linguistically sound target sentence may not have been selected by the runtime at all.

Configure the appropriate provider and linked String Table Collection. Play a known line outside the editor’s Localization Tables window. Record the precise locale, screen or story position, build identity and whether the defect reproduces after a clean start. A correction is accepted only when the relevant player action works, not merely when an editor warning disappears.

7. A player’s choice produces the wrong apparent promise

The translated option is semantically different from the action performed. Start by checking the actual user-facing state and locating the last point where the correct translation or correct branch was observed. This distinction matters because a linguistically sound target sentence may not have been selected by the runtime at all.

Compare the target wording with the actual branch consequence and rewrite the option. Ask a first-time target-language tester what they expect before clicking. Record the precise locale, screen or story position, build identity and whether the defect reproduces after a clean start. A correction is accepted only when the relevant player action works, not merely when an editor warning disappears.

8. Plural sentences fail only at count zero

The formatting logic lacks the target language’s grammatical case. Start by checking the actual user-facing state and locating the last point where the correct translation or correct branch was observed. This distinction matters because a linguistically sound target sentence may not have been selected by the runtime at all.

Review supported plural markup and test count boundaries in the running version. Repeat with zero, one, two, and a larger count. Record the precise locale, screen or story position, build identity and whether the defect reproduces after a clean start. A correction is accepted only when the relevant player action works, not merely when an editor warning disappears.

9. A long choice cannot be selected

Text overflow changed the button’s readable label or hit area. Start by checking the actual user-facing state and locating the last point where the correct translation or correct branch was observed. This distinction matters because a linguistically sound target sentence may not have been selected by the runtime at all.

Adjust layout and wrapping without reducing accessibility. Use keyboard and pointer selection on the longest target string. Record the precise locale, screen or story position, build identity and whether the defect reproduces after a clean start. A correction is accepted only when the relevant player action works, not merely when an editor warning disappears.

10. An in-progress conversation mixes languages

Current text and cached audio were not refreshed under the locale-switch policy. Start by checking the actual user-facing state and locating the last point where the correct translation or correct branch was observed. This distinction matters because a linguistically sound target sentence may not have been selected by the runtime at all.

Define a single transition behavior and update provider state consistently. Switch twice mid-scene and replay from save. Record the precise locale, screen or story position, build identity and whether the defect reproduces after a clean start. A correction is accepted only when the relevant player action works, not merely when an editor warning disappears.

11. A release has missing subtitles

Translated files or localization assets were not included in the player build. Start by checking the actual user-facing state and locating the last point where the correct translation or correct branch was observed. This distinction matters because a linguistically sound target sentence may not have been selected by the runtime at all.

Inspect the exact build artifact and its configuration, not the editor folder. Reinstall from a clean download and play an affected branch. Record the precise locale, screen or story position, build identity and whether the defect reproduces after a clean start. A correction is accepted only when the relevant player action works, not merely when an editor warning disappears.

12. One ending is never tested

The test plan concentrated on the shortest happy path. Start by checking the actual user-facing state and locating the last point where the correct translation or correct branch was observed. This distinction matters because a linguistically sound target sentence may not have been selected by the runtime at all.

Include a branch-coverage table with each ending and conditional route. Mark completed path IDs and capture the ending’s final dialogue. Record the precise locale, screen or story position, build identity and whether the defect reproduces after a clean start. A correction is accepted only when the relevant player action works, not merely when an editor warning disappears.

13. Target text contains literal curly braces

Inline placeholders or markup were treated as ordinary prose. Start by checking the actual user-facing state and locating the last point where the correct translation or correct branch was observed. This distinction matters because a linguistically sound target sentence may not have been selected by the runtime at all.

Restore placeholders according to the current format and inspect variable substitution. Run the line with a sample name and numeric count. Record the precise locale, screen or story position, build identity and whether the defect reproduces after a clean start. A correction is accepted only when the relevant player action works, not merely when an editor warning disappears.

14. An older version’s tutorial no longer works

The installation uses a different Yarn Spinner version from the documentation example. Start by checking the actual user-facing state and locating the last point where the correct translation or correct branch was observed. This distinction matters because a linguistically sound target sentence may not have been selected by the runtime at all.

Match steps and provider names to the installed project version. Document the version used for QA and verify an actual imported translation. Record the precise locale, screen or story position, build identity and whether the defect reproduces after a clean start. A correction is accepted only when the relevant player action works, not merely when an editor warning disappears.

A language-quality testing matrix that goes beyond string counts

Meaning and decision

Review a direct instruction, a tentative request, a refusal and a consequential choice in a branching railway-station story where a lost traveller asks for directions, chooses a ticket, changes platforms and eventually receives a spoken departure announcement. Ask a native-language reader to paraphrase each action before execution. Similar words are not required, but the degree of obligation, knowledge and risk must remain accurate.

For acceptance, record the exact test state and its observed result. Separate linguistic defects from interface faults, stale data, missing assets and changed gameplay. These distinctions tell the team who should repair the issue and whether the next release must be blocked.

State and branch parity

Capture a small set of authoritative game-state values before and after important choices. Confirm that language changes the presentation, not the action’s hidden effect. Where a local adaptation intentionally changes puzzle design, treat it as a tested product variant rather than an unrecorded linguistic correction.

Typography and device behavior

Use the longest approved target-language menu label, a phrase with accented or non-Latin characters, a number embedded in prose and punctuation at the end of a line. Test actual fonts, direction, wrapping, focus and readability on supported devices.

Missing translations and fallback

Select one deliberately missing noncritical string in a test build and confirm the declared fallback. Confirm that missing critical warnings and options are reported as release blockers. A visible English fallback should never be counted as a completed translation.

Release packaging and accessibility

Install from the same artifact the public receives. Repeat the first meaningful interaction without editor data or local caches, then test keyboard and touch navigation as appropriate. Use a reader who can report confusion, not only a script that sees successful file loading.

Four-week Yarn Spinner localization and validation plan

Week 1: source map and controlled scope

Tag every dialogue line and option, map branches, select built-in or Unity Localization as the owner, and export a baseline with protected structural columns.

The week’s exit test is an actual player journey with a named source version and target language. Capture what passed and what remains incomplete. Keep the scope small enough to review fully; adding a language name to a menu is not a substitute for tested comprehension. The plan should be adapted to the team and game’s scale, not treated as a promise that every project can finish in exactly four weeks.

Week 2: first complete target-language experience

Translate a complete conversation route, import it, verify locks and placeholders, and check one language switch with text-only and audio-enabled settings.

Week 3: coverage, variation and repair

Review alternate dialogue branches, formal/informal voice, counts, fonts, audio assets and accessibility; fix any mismatched line IDs or stale target text.

Week 4: release proof and maintenance

Freeze source and localization tables, produce a clean Unity player build, test every ending class and retain a line-ID-based coverage and release report.

Yarn Spinner localization: frequently asked questions

Do I need #line tags for translations?

Stable explicit line IDs strongly reduce translation breakage when scripts change. The current documentation recommends tagging lines before export and explains that location-derived IDs can move when the source changes.

For this particular project, the best next step is to test the answer against the real scene and release configuration. Preserve the source meaning and verify what the player actually experiences rather than relying on a file existing or a setting appearing in an editor.

Should translators modify the ID and lock columns?

No. Those fields connect text to runtime lines and source revisions. Treat them as protected data, compare them after CSV round trips, and ask translators to work in the intended translation fields.

How does Yarn Spinner handle multiple languages?

Its localization system associates language-specific strings with line IDs. In Unity you can use its built-in CSV approach or connect to Unity Localization’s String Table Collections and a localized line provider.

Can I reuse Unity Localization instead of Yarn’s built-in system?

Yes, the Unity integration is documented. Choose one primary ownership model, configure the String Table Collection and line provider, and retest dialogue and localized assets together.

Can voice acting be localized per line?

A stable line ID can associate a translated sentence with voice or other assets. Check the selected asset provider and language-specific folders or tables, and report text-only and voiced coverage separately.

How should I handle plural messages?

Use the formatting capabilities of the actual Yarn Spinner version and test the grammar in context with real values. Do not assume English singular and plural patterns describe the target language.

What is a sensible first release?

One additional language with complete core routes, reliable language selection, accurate choices and accessible subtitles is more credible than many partial untested editions.

Why is my translated CSV ignored in the build?

Possible causes include incorrect language configuration, an unreadable CSV, wrong line IDs, a mismatched line provider or omitted build assets. Trace one known line from source tag through the runtime view.

Primary documentation and further reading

These are technical starting points rather than substitutes for version-specific testing. The workflow above combines the documented behavior of Yarn Spinner with editorial and release practices. Always confirm features against the actual version of the game engine or library that will ship.

For the broader principles of transferring meaning across languages, see Master Art of Translation: The Complete System. For other tool-specific implementations, use the Translate Like a Pro series index. This guide focuses on Yarn Spinner projects; it is not a substitute for general literary translation advice or unrelated language-learning articles.

Final release standard: a player can understand, decide and recover

The purpose of localization is not to increase the number of entries in a file. A successful edition lets a reader choose a language, understand a meaningful situation, make the intended decision and recognize its result. For Yarn Spinner, that requires text, resource identities, program logic, rendering and delivery to agree. Maintain honest coverage records, preserve the author’s intentions and repeat the same player journeys after changes.

Translate Like a Pro | 7040 — Yarn Spinner Line Tags, Localised CSV Dialogue, Voice Assets and Unity Release QA