Description

multifariousYAML File Type for Trados Studio – User Guide

The full walkthrough for translating YAML locale files in Trados Studio: what the file type reads, how to set it up against your own files, and how to deliver files a developer can drop straight back into their build.

1. What problem this solves

YAML holds much of a software product’s text: application strings, website copy, product catalogues, help text.  It arrives as .yaml or .yml files that must be returned with the same structure, just translated.  YAML is whitespace-sensitive, comment-carrying and stylistically fussy; a file that comes back re-serialised – keys reordered, quotes changed, comments gone – breaks builds and code reviews even when every translation in it is perfect.

This file type changes only the translated values and leaves every other byte of the file alone. An untranslated file round-trips byte for byte.  In a file holding several languages, the languages you are not translating are untouched.

 The Studio editor with a multilingual YAML file open – keys visible in the document structure column, segments in the editor, and the Preview pane alongside showing the key/source/target table with the active segment highlighted.

2. What it reads, and what it delivers

Your file	How it is read	What you deliver
One language per file (title: Welcome)	Every value is source text	A translated copy of the file, structure intact
Languages keyed under each value (de: / en: / fr:)	Detected automatically when the keys are language codes	The same file, your target language’s values updated, every other language untouched
Languages under opaque keys (col1: / col2:, source: / translation:)	You point at the level and map each key to a language	As above
Many target languages at once	One Studio project, one target file per language – or one batch task	A single multilingual file carrying every target language

The delivered file is the original byte stream with translated text substituted in.  Key order, quoting style, indentation, comments, blank lines and document markers all survive because they are never taken apart in the first place.

3. Installation

1. In Trados Studio, open the integrated AppStore (Welcome view > RWS AppStore) and search for multifariousYAML File Type for Trados Studio – or download the .sdlplugin from the AppStore website and double-click it.

2. Restart Studio and accept the plugin when asked.

3. The file type appears under Options > File Types as Multilingual YAML, with four settings pages: Multilingual files, Monolingual files, Existing translations, and Embedded content and placeholders. Files matching *.yaml;*.yml are now accepted in projects.

Requires Trados Studio 2026 on Windows.  Nothing else – the YAML reading library ships inside the plugin.

The Options dialog with the File Types tree expanded, Multilingual YAML selected and its four settings pages – Multilingual files, Monolingual files, Existing translations, Embedded content and placeholders – visible beneath it.

4. What gets translated – and what does not

Offered for translation:

• Every value with text, at any nesting depth, in every document of a multi-document stream.

• Values that are only numbers – deliberately. Studio localises numbers (decimal separators, digit grouping) only in segments it was given; skip them and a price formatted 1,299.99 ships that way into a locale that writes 1.299,99.

• Comments, if you ask for it (off by default).

• The single stored copy of an anchored value (&name), once – provided that copy belongs to the language being translated.  An anchor sitting outside the language axis, one copy serving every language at once, is not offered: translating it would change all of them, so it stays exactly as it is and the conversion messages name it.

Not offered:

• Keys – they are identifiers the software looks strings up by, and changing them breaks the lookup.  Keys appear in the document structure column so you always know where you are.

• Alias sites (*name) – the file holds that text once, so it is translated once, at the anchor; the locked copies follow automatically in the delivered file.

• Values tagged !!binary – base64 data by the file’s own declaration, never a segment, in any mode, with no setting needed.  The blob round-trips untouched like everything else.

• In a file with a language axis: every language that is not your source or target, and anything your exclusion rules remove – each rule shows you what it removes before you commit to it.

• In monolingual mode: whatever the scope rules on the Monolingual files page leave out (section 7).  Those rules alone decide – the exclusion rules govern files with languages in them and play no part in a monolingual file.

• A comment sitting on a value the rules leave out – excluded, or outside the monolingual scope – is left out with it.

5. Your first project

1. Set up once: open Options > File Types > Multilingual YAML > Multilingual files and load a sample file of the kind you will translate (section 6 walks through this page).  For a conventional file – language codes as keys, or one language throughout – the defaults are already right and you can skip straight on.

2. Create the project with your .yaml/.yml files, source and target languages as usual.

3. If the files already carry some translations, run the batch task Import YAML translations (section 9) so that work arrives in the editor for review instead of being retyped.

4. Translate.  Values appear as segments; the key path for each segment is shown in the document structure column on the right of the editor.  Placeholders and embedded markup appear as protected tags – keep them.

5. Deliver with Save Target As – or, for one file carrying every language, the Generate multilingual YAML batch task (section 9).

Reading the segments

• The document structure column (far right) shows each segment’s key path – products > kettle > name – so identical strings in different places stay distinguishable.

• Locked segments are alias sites; their text lives elsewhere in the file (section 4).

• Tags inside segments are protected placeholders ({name}, %s, %{count} and similar) or embedded markup handed to another file type.  Translations keep them; QA checks them like any other tag.

The editor on a translated multilingual file – the document structure column showing key paths and an explanation of the locked alias segments that are also visible, and a segment containing a protected placeholder tag.

6. The Multilingual files settings

This page decides how your files are read, and it works from your own file: load a sample and every list on the page fills with that file’s real keys, so you recognise rather than guess.  The sample itself is not saved – only your choices are – and the settings apply to every YAML file in the project, so pick a typical one.

At the very top sits the mode: Files hold several languages, ticked by default.  Its opposite number, Files hold a single language, sits at the top of the Monolingual files page, and only one of the two can be active.  Untick this one and every file is treated as monolingual: the language sections below turn grey, and translations go to a separate file per language instead of back into the original.

 The Multilingual files page with a sample file loaded – the mode box at the top ticked, the path in the Sample file box and the summary line beneath it stating the values and keys counted and the languages found.

Where are the languages?

Load a sample and every place in your file that could hold the languages appears as a row – each row a complete reading of the whole file, not a part of it, and exactly one of them right.  Keys that are recognisable language codes (de, en-GB, pt_BR) are found for you, and that reading arrives already ticked as Recommended – use this default setting and the file type keeps reading every file for itself, the idea being this allows you to use differently structured files in one project.  Keys that say nothing about language (col1 / col2, field_01) need to be selected: tick the row whose values hold the languages, and the level in that row will be used for every file.  Values used counts how many of the file’s values each reading reaches (“All 16”, or “12 of 16”), so a choice that misses any should reflect exactly what it leaves out.

When a sample yields nothing detectable, a visual representation from your file is presented below the table and points at the suggested row to tick – and a file that later converts without any recognisable languages says so in Studio’s Messages window when the file is open in the Editor.

A file with no languages in it at all is the monolingual mode: untick the box at the top, or enable the Files hold a single language checkbox on the Monolingual files page (section 7).

When you tick a row, an excerpt of your own file appears under the table with the keys that row treats as languages highlighted.  If the highlighted keys are plainly not languages, it is the wrong row, and you can see that without understanding anything about YAML structure.

The levels table with the Recommended row already ticked and a visual representation from your file beneath it highlighting the de and en keys of the loaded sample.  It also shows the expanded help – Which of these do I need? –  explaining the feature.

The same table with a wrong row deliberately ticked – the excerpt now highlighting ordinary section keys as if they were languages, and the visual representation from your file beneath clearly showing the result this choice would render.

Which key means which language?

One row per key found at the chosen level.  A key that is already a language code is filled in for you; anything else is left blank, because only you know that col2 (for example) means English.  Pick from Studio’s own language list – type to search by name or code, flags included.  The page counts your progress (“2 of 3 set”), and flags if you select the same language twice.

The key-to-language mapping on an eight-key multilingual sample – flags visible in the dropdowns and the “8 of 8 set” counter at the bottom right.

What should not be translated?

Everything with text is translated unless a rule excludes it, so a key added to the file later is picked up automatically rather than quietly missed.  These rules govern files with languages in them; a monolingual file is governed by the Monolingual files page alone, so a rule here can never quietly remove values over there.  Three kinds of rule:

• Key path with wildcards: metadata.**, items[*].id

• Key name by regular expression: (?i)_comment$

• Value by regular expression: ^\d+$, ^(true|false)$

Each rule’s row shows what it removes from the loaded sample, and the Check button previews the whole set – including rules that match nothing, which may mean a typo – so worth checking first.

The exclusions grid with two rules listed, their “Removes” counts shown, and the Check summary beneath reporting what the whole set leaves out of the sample.

Saving and segmentation options

• Copy source into empty targets – a value left untranslated can stay empty in the delivered file, or carry the source text so the file ships without gaps.

• Split block scalars – a multi-line value stays in one segment by default, preserving its line structure; switch this on before creating the project when the lines are really separate sentences.

7. Monolingual files settings

A clean locale file needs nothing here – every value is a string a translator should see, and that is the default.  But monolingual YAML often mixes prose with things that must not reach the editor: code snippets in tutorials, markup templates, identifiers, configuration data.  The Monolingual files settings page scopes translation to exactly the right values, and the whole job is done by clicking.

At the top of the page you’ll find the Files hold a single language checkbox – the same mode switch as the box on the Multilingual files page.  Tick it and every file is read as holding a single language, with the settings below deciding what it offers; untick it and this page greys out and plays no part, exactly as the language sections grey the other way round on the Multilingual files page.

Load a monolingual sample on the page, select Translate only the values I choose, and build the selection as rules:

• From the tree: tick values or whole branches – a branch tick takes everything beneath it – then Add include rule or Add exclude rule.  Ticks become generalising path patterns (tutorial.**), so keys a later file adds under a ticked branch are covered.

• From the search: type into Find and the tree narrows to matching keys and values.  The add buttons then turn the search itself into a rule – so “exclude every value containing 786″, a hundred strings scattered through the file, is one search and one click.  Tick the Regular expression box to test a pattern live first: the tree shows exactly what it matches, an invalid pattern says so under the box, and the rule carries the same pattern.

Rules run top to bottom, and the last one that matches a value decides it – include a whole branch, add an exclusion beneath it, re-include a special case beneath that, exactly as written.  Each rule can be edited in place (action, kind, pattern), suspended without deleting, reordered and removed; hover over a rule to see how many of the sample’s values it matches.  And the page keeps score everywhere: the preview line states “5 of 8 values will be translated”, and the tree greys out whatever the rules currently leave out, so a wrong rule looks wrong before you use it to find out.  Don’t forget the Trados Studio preview feature for file types also works in conjunction with these settings so you can also preview the file without having to open it in the Studio Editor to test.  When comments are set to be translated, they appear in the tree too – green, italic, marked #, beside the values they sit on, with no tick box of their own – they grey with the rules’ verdict like everything else, the search finds their text, and the preview line counts them separately (“… and 5 of 14 comments”), so the page predicts exactly what Studio will show, comments included.

The Monolingual files page in action – the tree, some entries greyed out, green #-marked comment rows among the values, and beneath it the ordered rule list at full width with two include rules for a branch and an exclude rule below it.

The Find box with the Regular expression checkbox ticked and a pattern such as \d+ typed against the monolingual sample – the tree narrowed to the address lines of the legal imprint, ready to become an exclude rule.

The scope applies while the monolingual mode is ticked, and these rules alone then decide what a file offers – comments extracted as segments included, so excluding everything that contains a phrase removes the comments that contain it too.  The Multilingual files page’s exclusion rules govern files with languages in them and play no part here, so the two pages can be configured – and their settings exported – independently.

8. Existing translations, embedded content and placeholders

• Existing translations controls what the Import YAML translations batch task does with translations found in your files: the status they arrive at (Draft by default, so imported work is reviewed) and whether work already done in the project is kept – it always is; the import never overwrites a translated segment.

• Embedded content and placeholders hands values containing markup to the matching Studio file type – HTML in help text, for example, gets real tag protection and preview – and applies protected-text patterns on top: {name}, %s, %{count} and your own additions. Both at once, which Studio’s built-in file types do not offer.

The Embedded content and placeholders page, showing the embedded file type selection and the placeholder pattern list.

9. Multilingual projects and the batch tasks

A Studio project delivers one target file per language pair.  For multilingual YAML that is only half the story, and two batch tasks complete it.

Import YAML translations

A project converts each file before it knows your target languages, so translations already sitting in a multilingual file cannot be paired up at that moment – every target segment arrives empty.  Run this task once (Batch Tasks > Import YAML translations) and the translations are filled in from the files, at the status you chose, without ever overwriting work already done in the project. If you are working with the professional version of Trados Studio this task can be added to a set of custom batch tasks so the project is created with the source and target ready populated before you start.  For the freelance version the task would be run after the project has been created.

A single-file document does not need it: opened alone, the target language is known from the start and the pairing happens by itself.

Generate multilingual YAML

Save Target As gives you one file per target language, each holding that language’s translations and nobody else’s.  The Generate multilingual YAML task instead writes every target language back into one file: it rebuilds from the pristine original in a single pass with all languages applied, and puts the result in the project’s Multilingual folder.  Running it twice gives the same answer – there is no accumulating shared file to protect.

The Batch Tasks menu open on a project, with Import YAML translations and Generate multilingual YAML listed among the tasks.

10. Saving the target

1. Save the bilingual document first – Ctrl+S. Studio generates targets from the last-saved state, so a tab showing an asterisk means edits that will not reach the target.

2. File > Save Target As (or the batch task, section 9).

3. For a multilingual file, open the result and check: your language’s values translated, everything else – other languages, comments, formatting – exactly as it arrived.

11. Verifying the delivered file

Two checks confirm the delivered file:

• Diff it against the original.  Any text comparison tool (even git diff on the developer’s side) should show changes only on the lines you translated.  This is the check the file type’s own test corpus is held to.

• Parse it.  Any YAML-aware editor or an online validator confirms the file is still valid YAML – it always should be, since nothing structural was touched.

12. Workflow recipes

• Piloting a new file set: load the most complex file as the sample, check the levels table’s Recommended row and its excerpt, run the exclusion Check, then pseudotranslate a copy and diff it against the original before committing the real project.

• Opaque labels arriving mid-project: col1/col2 files can join a project at any time – the level choice and mapping are per file type configuration, so set them once and every file in the project follows.

• Translation memory strategy: keys never enter segments, so TM matches are pure text and survive restructuring of the YAML.  Comments extracted as segments (if you switch that on) carry their own context.

13. Troubleshooting

Problem	Cause and fix
Target segments empty though the file carries translations	Project conversion happens before target languages are known. Run Import YAML translations once.
One file per language, but one file with all languages needed	Run Generate multilingual YAML; the result is in the project’s Multilingual folder.
“No key matches the project language” / “two keys claim the same language”	An ambiguous mapping is reported instead of guessed.  Fix the mapping on the Multilingual files page – one key per language.
Detection finds no languages in a col1/col2 file	It never could – only you know.  Tick the row that holds them and map the keys (section 6); a table on the page and a warning in the Messages window both point there.
A segment is locked	It is an alias site.  If the anchor sits in your language’s values, translate it and the copies follow; if it sits outside the languages entirely, one copy serves them all and it should not be translated (section 4).
Number-only segments in the editor	Deliberate – Studio only localises numbers it was given (section 4).  Exclude with ^\d+$ if you must.
A monolingual file offers its code snippets or data	Scope it on the Monolingual files page: tick the prose, or search-and-exclude the rest (section 7).
A value vanished and no rule seems responsible	Check the rule kinds: an unanchored regex like \d+ means “contains a digit anywhere”, not “is a number”.   The diagnostics log (see the site guide) records the rules in force at each conversion.
Translations missing from the saved target	Ctrl+S first, then Save Target As – targets are built from the last-saved state.
A settings change seems to have no effect	Segmentation-affecting settings apply at conversion.  Recreate the project, or re-add the files.

14. Limitations and feedback

• Keys are never translated. By design – they are identifiers – but if your workflow genuinely requires localised keys, this file type will not do it.

• An anchored value has one translation. The file stores the text once, so it cannot carry a different translation per alias site – and an anchor defined outside the languages and referenced from several of them cannot be translated at all, since its one copy serves every language at once. If a shared value needs to diverge per language and per site, that is a file design question for the developers.

• Segmentation-affecting settings bind at project creation. Exclusions, comment extraction and block scalar splitting decided after conversion require recreating the project to take effect.

• Flow scalars on one line ({ key: value, key: value }) are handled, but a file written entirely as one flow mapping is a stress case the corpus covers only lightly.

If a file opens strangely, a structure is misread, or a convention cannot be expressed in the exclusions – send it (anonymised as needed).  Every report makes the file type more useful for everyone who works with these files.

Copyright 2026 multifarious. All rights reserved. YAML parsing powered by YamlDotNet (MIT licence).

AppStore listing: https://appstore.rws.com/plugin/488  – full documentation: https://multifarious.filkin.com/product/yaml-file-type/