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.

Watch a video where Yarn Spinner developer Jon Manning walks you through using the Built-In Localisation System:

Set Up Localisations

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:

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 form, that contains a translated version of your dialogue. Yarn Spinner can generate a strings file for you, based on the in the dialogue.

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:

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.

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 .

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.

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 fetches assets from a Yarn Project, 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.

Every line of dialogue that Yarn Spinner works with has a unique identifier, which we call the line ID. Yarn Spinner uses the line ID to look up what specific content to show the player, along with other information like which language the user is using. All lines are given a line ID, even if one isn't specified in the script.

The line ID is an important part of your dialogue production process. When a line of dialogue is written in a Yarn Spinner script, a number of additional assets often need to be produced to support it - for example, voice-over audio, translations of the line into other languages, additional voice-over audio for the translations, animation, and more. Each of these additional assets are often handled by different people, or often different companies. All of these assets for this single line are linked together via the line ID.

Different studios have different preferences and requirements for their line IDs - some teams need them to carry lots of information, like the character's name, the point in the game's story at which the line appears, and so on, while some teams need them to be extremely concise. To support this, Yarn Spinner allows you to configure how line tags are generated.

Adding Line Tags

Every line that Yarn Spinner works with has a line tag. If you don't add one yourself, Yarn Spinner automatically creates an internal line tag. If you're working alone, and you're making a text-only game that only needs to work in a single language, this can be all you need. However, if you're going beyond these bare basics, read on.

Adding Tags Manually

You can manually add line tags to lines by writing them in your Yarn Spinner script. To do this, add a #line: hashtag to your line, followed by the unique line ID.

All line IDs in a Yarn Spinner project must be unique across all of your files. If two lines have the same ID, you'll get an error on both of them.

You can add line tags to your files in Unity. To do this, select your Yarn Project asset, and click the Add Line Tags to Yarn Scripts in the Inspector. Yarn Spinner for Unity will add unique tags to every line that doesn't already have them, and then re-import your project.

You can control which tags are added by turning on the Custom Line Tagging in the Inspector. For more information on controlling these tags, see below.

You can add line tags to your files in the Visual Studio Code editor. To do this, open the Yarn Spinner sidebar, and find your Yarn Spinner project. Right-click it, and choose Add Line Tags.

You can control which tags are added by the extension. For more information on controlling these tags, see below.

There are three ways that Yarn Spinner can generate the line IDs:

• The random tagger creates a short, unique, random, hexadecimal line ID.

• The descriptive tagger creates a longer line ID that includes the node name, a sequence number, and the character name (if present.)

• You can also provide your own custom line tagger to suit your own needs.

If you're adding line tags in Unity, you can control which tagger is used by turning on the Use Custom Line Tagging option in the Inspector for your Yarn Project.

If you're adding line tags in Visual Studio Code, you can control which tagger is used by opening the Yarn Spinner sidebar, and clicking the Settings button. In the Editing section, find the Tag Style dropdown, and select the tagger you want to use.

The random line tagger creates a short hexadecimal line ID. This is the original line tagger that Yarn Spinner has used since the very first release, and it's useful when you need a short ID that doesn't take up much space in your Yarn Spinner scripts.

Here's an example of a random tag:

The descriptive line tagger creates a longer line ID that contains information about the line, and its position in your story. The tags generated by the descriptive tagger contain the name of the node, a sequence number, and optionally the character name.

Here's an example of a descriptive tag:

The descriptive tagger adds a sequence number after the node name, which can help when sorting the tags alphabetically (such as when looking at a list of audio files). Each node gets its own separate sequence.

The tagger tries to leave gaps between lines, which makes it easier to insert new lines later if you need to. If you add line tags using the descriptive tagger to an otherwise un-tagged line, each of the line tags will be given a sequence number 100 higher than the last line.

For example, the following lines:

Would be given tags like this (assuming that this is all in a node called `Tutorial`):

If you insert new lines of dialogue in between lines that already have tags, and then re-run the tagger, the tagger will attempt to fit in new sequence numbers between the lines that have them.

For example, adding a line between Tutorial_0200_Alice and Tutorial_0300_Bob like this:

Would result in a line tag like this:

If you want to take complete control over how Yarn Spinner generates custom tags for your lines, you can create a custom tagger.

To create a custom tagger in your Yarn Spinner for Unity project, create a new C# script that implements the ILineTagGenerator interface.

Here's a very simple custom line tagger that uses the node name and the index of each line to produce line tags.

Once you've created this script, you can use it to tag lines. Select your Yarn Project, turn on custom line tagging, and select your custom tag class. Next, click Add Line Tags, and your tagger will be used to add tags.

Localization is the process of translating and adapting content to a specific language, region or culture.

Yarn Spinner 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.

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.

Working with Localisation

Yarn Spinner makes it easy to add multiple languages to your game. The gist is:

1. Select your Yarn Project in the Assets panel

2. Click "Export Strings as CSV" in the Inspector

3. Translate the exported CSV file

4. Import the translations back into your project

You can use either:

• : Manage translations directly through Yarn Spinner

• : Integrate with Unity's Localisation package

• 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 Files: 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.

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 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 automatically 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 customise how Yarn Spinner generates line tags for your script. For more information, see .

Once you've added line IDs to your Yarn scripts, they're ready to be used in your game's localisation system. You can choose between using the , in which case Yarn Spinner can prepare your string tables and fetch content from those tables at run-time, or our .

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.

Watch a video where Yarn Spinner developer Jon Manning walks you through using Yarn Spinner with Unity's Localisation package:

Getting Started

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.

For Unity Localization

1. Install the Localisation package

2. Create a new Localization Settings in the Project Settings - Localization screen:

1. Create at lease one Locale in the Project Settings - Localization view.

2. Create a String Table Collection via Window menu -> Asset Management -> Localization Tables.

3. Check "Use Unity Localisation System" in your Yarn Project, and assign the String Table, and click Apply.

1. Verify that the String Table (viewable by Window menu -> Asset Management -> Localization Tables) contains your Yarn Spinner Script's lines.

2. In the Inspector for your Dialogue Runner, click the "Add Unity Localized Line Provider" button:

1. This will add a component to your GameObject. Find it, and assign your String Table Collection to the Strings Table field:

Once you have followed these instructions, your project should now:

1. Have the Unity Localization package installed

2. Created and configured one or more Locales for your project

3. Created a string table collection.

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:

1. Select the Yarn Project, and go to its Inspector.

2. Enable the Use Unity Localisation System setting.

3. Set the Base Language to your desired language. This must be ensure its one of the locales that you have configured for your project.

4. In the String Table Collection

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 receives line IDs from the Yarn Project, and must determine what localised content should be shown to the player, using a . In order for the Dialogue Runner to fetch localised data from the Unity string table, you use a .

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.

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.