This page covers what you need to know to use the internal localisation system built into Yarn Spinner. This supports both the localisation of the text, so the lines themselves, and your assets needed for them.
The other option for localisation is to use the Unity Localization package. The Unity Localisation package has more features, but is more complex.
Watch a video where Yarn Spinner developer Jon Manning walks you through using the Built-In Localisation System:
When you want to prepare a Yarn Project for an additional language, you add a new Localisation in the Yarn Project.
Localisations are how you tell Yarn Spinner where to find the localised lines, and the localised line assets, for a given language.
To create a new Localisation, open the Localisations list in the Yarn Project's Inspector, and click the + button.
Localisations have the following properties:
Language ID
The language for this localisation.
Strings File
Assets Folder
A folder containing the localised assets for this localisation.
Your project always includes at least one localisation, which is for the base language.
After you've set up a localisation, you can translate your dialogue into that localisation's language. To do this, you generate a strings file.
A strings file is a text-based spreadsheet, in comma-separated value form, that contains a translated version of your dialogue. Yarn Spinner can generate a strings file for you, based on the line IDs in the dialogue.
You don't need to create a strings file for your base localisation, because Yarn Spinner creates that for you by reading your source Yarn scripts. Any localisation whose language ID is the same as your base language will be marked as 'Automatically included'.
To create a strings file, select a Yarn Project, and click the "Export Strings and Metadata as CSV" button. Unity will ask where you want to save the strings file (the metadata file will have the same name as the strings file, but with a "-metadata" appended to it).
A strings file has the following structure:
language
The language code for this line.
When you export a strings file, this will be the Yarn project's base language.
id
The line ID for this line.
text
The text of the line, in the language indicated by the language column.
file
The file that the line was originally found in.
node
The node that the line was originally found in.
lineNumber
The line number of the file that the line was originally found in.
lock
A unique value that Yarn Spinner uses to detect if the line has been modified since the strings file was generated. Don't modify or delete this value.
comment
A note indicating the intent and tone of the line. This can be useful for translators who may not have the same background or context for how the line should be delivered.
Once you've exported a strings file, you can translate it into another language: for each row in the database, change the language column to the new language you're translating into, and the text column to the translated text of the line.
Only the language and text columns should be modified by the translator. Don't modify the others; in particular, if you modify the value in the id column, Yarn Spinner won't be able to link the translated line to the original version.
The metadata file contains the id, file, node, and lineNumber columns (which have the same values as in the strings file). Additionally, it contains a metadata column with all the metadata of a line. Only lines that contain metadata will be present in this file. For more information on metadata, see Tags and Metadata.
You can also provide the metadata file to the translator to give them more context and improve localisation accuracy.
Once you have a strings file that's been translated into your target language, you can add it to your Localisation. To do this, drag and drop the translated strings file into the Strings File property of your localisation, and click Apply.
It's possible to update a strings file after you've made changes to your source scripts. For example, you might have added or removed lines, or made changes to the text.
To update a strings file, click the Update Existing Strings Files button at the bottom of the Inspector.
Yarn Spinner will update every strings file that's been added to the Localisations list: new lines will be added, removed lines will be deleted, and lines whose original text has changed since the last time the file was updated will have the text "NEEDS UPDATE" added to the end. This allows you to more easily find which lines need an updated translation.
Localised line assets are assets that are associated with a particular line, in a particular localisation. The most common example of this is voice-over lines, which are audio assets that are associated with each line.
Line Providers are responsible for fetching the appropriate assets for a given line and language. For example, the Audio Line Provider fetches audio clips, and provides them to voice-over dialogue views.
The specific localised line, and localised line assets, that a line provider fetches depends on which language they have been configured to fetch.
The Text Line Provider has a single language option, which controls which language the line will appear in.
The Audio Line Provider has two language options: the language of the text, and the language of the audio files that are retrieved. This means that you can configure it to provide text in one language, and audio in another.
If a line provider is asked to retrieve content for a language that it doesn't have any assets for, it will retrieve the base language version instead.
In addition to Yarn Spinner's own built-in localisation system, your game can also use the Unity Localization package.
Both the Unity Localization and Built-In Localisation approaches are very similar to one another, but there are some caveats and extra steps to make them play together.
The Built-In Localisation system is simpler, but has fewer features.
In this document, we'll refer to the 'Localization' package that Unity provides as 'Unity Localization', to reduce the chance of confusion.
Watch a video where Yarn Spinner developer Jon Manning walks you through using Yarn Spinner with Unity's Localisation package:
Before doing anything with Yarn Spinner, you will need to set up your Unity project to use the Unity Localization system. To install and set up Unity Localization, follow the instructions on the Unity Localization package's documentation.
Once you have followed these instructions, your project should now:
Have the Unity Localization package installed
Created and configured one or more Locales for your project
Created a string table collection.
When localising your game's dialogue using Yarn Spinner, we recommend creating a separate string table collection for your dialogue, set apart from other localised content like button labels. It can make it a little easier to manage.
With these done you should now have your project set up correctly, and have a string table collection for your locales with no entries inside. Yarn Spinner will fill this string table with content that it extracts from your Yarn Scripts.
To fill a string table with content from a Yarn project, follow these steps:
Select the Yarn Project, and go to its Inspector.
Enable the Use Unity Localisation System setting.
Set the Base Language to your desired language. This must be ensure its one of the locales that you have configured for your project.
In the String Table Collection field, add the String Table Collection that you want to populate with line content.
Click Apply.
You can check that the string table has been filled with content by opening the Window menu, and choosing Asset Management -> Localization Tables. You can then view the contents of your string table. The Key of each string will be the #line ID from the Yarn files.
When the Yarn Project importer adds your lines into the string table, it uses the Base language field you set in the Inspector to determine which locale in your String Table Collection should have the lines added into.
If your project doesn't have a Locale which matches your Base Language, Yarn Spinner will attempt to find an appropriate Locale to use. To ensure that the importer uses the correct Locale, be sure to specify it in the Inspector.
When a Yarn script is run, the Dialogue Runner receives line IDs from the Yarn Project, and must determine what localised content should be shown to the player, using a line provider. In order for the Dialogue Runner to fetch localised data from the Unity string table, you use a Unity Localised Line Provider.
The Dialogue Runner's Inspector will tell you when you need to use a Unity Localised Line Provider. You can click the button it provides to quickly add and configure one. You can also set one up manually, using the Add Component menu.
To configure it, all that needs to be done is hook your string table collection up to the Strings field of the Unity Localised Line Provider.
During gameplay, the Unity Localised Line Provider will fetch content from your string table depending on the game's current locale setting. You can control this at run-time by using the locale selector at the top-right corner of your Game View.
In addition to localising the strings that make up your lines, you can also localise assets that go with each line, such as voice-over audio, or custom objects that store other localised data.
To localise assets in Unity Localisation, you create and populate an Asset Table. Yarn Spinner doesn't automatically populate Asset Tables for you like it does String Tables, because Yarn Spinner doesn't manage your assets like it does with your lines.
Instead, you can create an Asset Table that contains assets with the same key as your lines. For example, if you have a line in your Yarn script that has the line ID "line:tom-1", then the string table will have an entry with the key line:tom-1. To create a voice-over asset to go with this line, you can create an asset table that also contains an entry with the key line:tom-1, and maps to an audio file.
The Unity Localised Line Provider will automatically match String Table entries and Asset Table entries if they have the same key, and then deliver them to your Dialogue Views for use. To do this, ensure that your Unity Localised Line Provider has an Asset Table configured in the Inspector.
As each node is entered the Unity Localisation Line Provider will begin loading all the required assets for every line and option in that node, and when you leave a node all assets are then released. We have found that as a default this works very well, but in some circumstances you will want more control over this. The most common reason for this is to preload multiple nodes worth of assets at once. This is supported but has a few steps and quirks to be wary of.
First you will need to get a list of all the node names for which you want to preload the assets. Once you have this you can use the GetLineIDsForNodes method on the Yarn Project to get a list of the line IDs for every line and option in the nodes. Next you will need to disable the automatic asset clearing on the line provider, you do this by setting the AutomaticallyUnloadUnusedLineAssets boolean to be false. With this done you can now use the PrepareForLines method to start the assets loading, and once that is finished your multiple nodes worth of assets have all been loaded.
Now the downside to this is because we can't know which assets you are finished with you will need to manually tell the line provider when to release the assets. You do this by calling ClearLoadedAssets which will release all loaded assets. It's important to note that calling ClearLoadedAssets will clear every loaded asset, so doing this while nodes are still being read will result in unusual behaviour.
Because both Yarn Spinner and Unity use the same marker for their string interpolation and manipulation ({ and }), you can't use the Unity Localization smart strings in Yarn Spinner content.
A Text Asset containing the translated lines for this Yarn Project's scripts. See for information on how to create these assets.
Localization is the process of translating and adapting content to a specific language, region or culture.
Yarn scripts are written in human-readable language. This is generally a single language, and (most of the time) will be written in the language that your development team primarily speaks. The language that a Yarn project is written in is called the base language.
However, if you want your dialogue to be understood by people who don't speak this language, you will need to translate it. Yarn Spinner is designed to make it easy to extract the user-facing text of your dialogue into a strings file, which can then be translated into a different language, and then loaded at run-time. You can translate your project into as many languages as you'd like, and Yarn Spinner will handle it for you automatically.
Yarn Spinner is also designed around the idea that a line of dialogue may have assets associated with it. Most commonly, this means an audio file that contains an actor performing the line, so that it can be used in your game as a voice-over. These assets are also localisable.
I just want to add voiceover in a single language. Why do I need to localise, too?
The philosophy of Yarn Spinner's approach to localisation is: if you want your dialogue to be text-only, and in a single language, you don't need to do anything at all. If you want to do anything else, you will need to set up a localisation and manage it using Yarn Spinner's processes.
We've found that most users who want to start using Yarn Spinner want to quickly get dialogue on the screen, and don't want to do lots of work to get the basics going. That's why we make the simple use-case (text only, a single language) as easy to use as we can.
However, if you're building a game that's voice acted, it makes your life significantly easier if you build your systems with localisation in mind from the start. Additionally, if you have the resources to add voice-over to your project, you should also have the resources to translate your game to other languages (even if you only have voice-overs in a single language.)
To that end, we designed it so that voiceover is intimately tied to localisation, so that you have to at least start thinking about localisation at the start of the process.
Localisation: A set of information that describes where to find text and assets for a given language.
Base language: The language that your Yarn script files are written in.
Strings file: A text document that contains translated versions of Yarn lines.
Line ID: A unique code that identifies a line of dialogue or an option in the original source text.
Localised line: The text of a line of dialogue, in a particular locale.
Localised line asset: An asset (for example, an audio clip) that's associated for a particular line, in a particular locale. For example, an audio clip containing the voiceover for the line "Hello there", in German.
Line provider: A component that receives line IDs from the Dialogue Runner, and fetches the localised line and localised line assets (if present) for the player's preferred locale.
To localise your Yarn scripts, you specify the 'base language' that your scripts are written in. You then add unique line ID tags to each line that identify each line. Finally, the localisation system reads your tagged lines and fills the string table for your base language. You can then add additional translations for your lines to the string tables for other languages.
Every Yarn script is associated with a base language. By default, Yarn Spinner sets the base language to that of your current locale. For example, if your computer is set to use Australian English, then Yarn Spinner will use that as the base language.
The base language of a Yarn Script is controlled by the Yarn Project that it's a part of. You can change the language of your base localisation by changing the 'Base Language' setting on a Yarn Project.
In order to match different versions of a line, you need to add a line id to each line of dialogue. A line ID is a tag that appears at the end of a line that uniquely identifies a line of dialogue in your game.
Here's an example of a line of dialogue with a line tag:
In this example, the line of dialogue has a line ID of 1a64a5.
Yarn Spinner can add line IDs to your dialogue for you. To do this, select your Yarn Project, and click 'Add Line Tags to Scripts'. Yarn Spinner will re-write all of the script files, adding a line ID to any line that doesn't already have one.
You can't generate a strings file unless all of the lines in all of the scripts in the Yarn Project have a line ID.
Once you've added line IDs to your Yarn scripts, they're ready to be used in your game's localisation system. Yarn Spinner works with the Unity-provided Localization package, and can prepare your string tables and fetch content from those tables at run-time.
If you'd prefer to not use Unity's Localization package, Yarn Spinner also provides a built-in localisation system, which is described in Built Yarn Spinner localisation system
