Found me on Upwork? If you found me through Upwork and want to work together, please contact me through Upwork. Messages from Upwork clients sent outside Upwork will not be answered.
Localization notes🌏 Localization

Unity Localization Package for Vietnamese: the complete workflow

Add Vietnamese (vi) to any Unity game via com.unity.localization: String Tables, TMP font atlas for diacritics, XLIFF export, and common Vietnamese text bugs.

Dao Huy (Lucas)7 min read8 sections
Unity Localization Package for Vietnamese: the complete workflow

💡 Unity's Localization package (com.unity.localization) adds Vietnamese (locale code vi) to any Unity game through five steps: install the package, add the vi locale, build a String Table Collection, fill in translations, and wire up LocalizedString components. The two non-obvious pitfalls: your TextMeshPro atlas must cover all 134+ Vietnamese diacritic glyphs, and UI containers need 15-30% extra width for Vietnamese strings.

Key takeaways

  • Install com.unity.localization via Package Manager; Vietnamese locale code is vi (BCP 47); Google Play lists vi as a fully supported store language.
  • String Table Collections export natively to XLIFF, so translators work from a standard file without accessing your Unity project.
  • Switch TextMeshPro to Dynamic atlas mode so all 134+ Vietnamese diacritic glyphs render at runtime without gaps.
  • Run pseudo-localization before translation to catch UI overflow early: Vietnamese strings average 20% longer than English.
  • Machine translation handles placeholder text in development; in-context review by a native Vietnamese gamer catches register and cultural issues before ship.

Why the Vietnam mobile gaming market rewards Vietnamese localization

Vietnam has over 77 million internet users and a fast-growing mobile gaming segment. Google Play lists Vietnamese (vi) as a fully supported app-store language for both store listings and in-app locale detection. Players on Vietnamese-language devices expect their games to match, and players who cannot read UI in their native language churn faster.

With 97 million Vietnamese speakers globally, adding the language is a real revenue decision, not a polish task. Chinese game studios are the largest source of mobile games entering Vietnam, and titles that ship with Vietnamese from day one see meaningfully higher day-7 and day-30 retention in the market.

How do you install Unity's Localization package and add the vi locale?

Open Window > Package Manager, switch to Unity Registry, search for "Localization," and install com.unity.localization (requires Unity 2021.3 LTS or later). Go to Edit > Project Settings > Localization, click Add Locale, check Vietnamese (vi), and confirm. Unity creates a vi Locale asset in your project.

Set a Default Locale (usually English en) and add vi as a supported locale. The System Locale Selector auto-detects device locale on Android (via Android system APIs), iOS (via preferred language settings), and Windows (via CultureInfo.CurrentUICulture). To force Vietnamese during Editor testing use this snippet:

// C# - force vi locale at runtime for testing
LocalizationSettings.SelectedLocale =
    LocalizationSettings.AvailableLocales.GetLocale("vi");

How do you structure String Table Collections for Vietnamese and export for translators?

A String Table Collection holds one row per string and one column per locale. Open it via Window > Asset Management > Localization Tables, click New Table Collection, select your locales (including vi), and name the collection. Best practices for Vietnamese:

  • Key naming: use dot-separated paths (ui.button.start, hud.label.hp, dlg.npc.guard.line_001) with no spaces.
  • Plural handling: Vietnamese has no grammatical plural. Where English needs {count:plural:apple|{} apples}, Vietnamese usually needs only one form, simplifying Smart Strings.
  • Preloading: enable preloading for HUD and core UI tables so strings are available on the first frame.
  • XLIFF export: go to Window > Asset Management > Localization Tables > Export, choose XLIFF 1.2 or 2.0, set source en and target vi, and send the .xliff file to your translator or CAT tool (Trados, memoQ, Smartcat). Import the translated file back and rebuild Addressables. Translators never need Unity access.

Why does TextMeshPro font atlas setup matter for Vietnamese diacritics?

Vietnamese writes with Latin letters plus six tone marks (sắc, huyền, hỏi, ngã, nặng, and ngang) stacked on vowels, producing 134+ distinct glyph variants. A Static TMP atlas built from ASCII characters will show boxes or question marks for letters like ả, ụ, ễ, or ồ.

The recommended fix: set your TMP font asset to Dynamic atlas mode (Atlas Population Mode: Dynamic in the Font Asset Creator). Unity renders glyphs on demand at runtime, covering the full Vietnamese Unicode range. For production builds where load time matters, export the character set from your String Table (Window > Localization Tables > Export Character Set), then bake a Static TMP atlas from that exact set. The result: no missing glyphs and no runtime atlas-build overhead.

What are the most common Vietnamese text bugs in Unity games?

  • Missing diacritics: Static TMP atlas without Vietnamese glyphs renders ô as o, ắ as a, making text unreadable. Fix: Dynamic atlas or a baked static atlas generated from your String Table's character set export.
  • UI text overflow: "Start" (5 chars EN) becomes "Bắt đầu" (7 chars VI). Fix: run pseudo-localization before sending to translators. The pseudo-localization tool inflates strings to simulate length expansion and flags tight containers early.
  • Hard-coded strings: any .text = "Start Game" in scripts bypasses String Tables entirely. Replace every hard-coded string with a LocalizedString reference.
  • Encoding corruption: Windows tools that save XLIFF as Windows-1252 silently corrupt Vietnamese diacritics. Unity's native XLIFF pipeline is UTF-8 by default; ensure your translators also export UTF-8.
  • Missing locale fallback: a key with no vi value and no fallback configured shows as an empty string. Set a fallback locale in Localization Settings.

What can you handle in-house, and when does a native Vietnamese game specialist pay off?

Your team can handle everything technical in-house: package setup, locale config, String Table structure, XLIFF export, TMP font atlas configuration, pseudo-localization testing, and a first machine-translation pass for placeholder text during development.

A native Vietnamese game translator pays for itself when:

  • Genre-specific terms are involved. Machine translation picks the wrong register for RPG skill names, MOBA items, and card-game mechanics almost every time, because those terms have established Vietnamese conventions that MT systems do not reliably know.
  • Dialogue has wordplay, cultural references, or regional idioms that need adaptation rather than literal translation.
  • Store listings on Google Play and the App Store must read naturally to Vietnamese players, not obviously machine-translated.
  • LQA on a physical device is needed. Only a native player can spot errors that read correctly on paper but sound wrong in context.

For in-context Vietnamese game localization from English or Chinese, Dao Huy's game translation service covers terminology management, in-context review, and LQA passes.

FAQ

Can I run my Unity XLIFF through DeepL or Google Translate directly?

Machine translation gives a usable first pass for placeholder text, but it consistently misses genre register. RPG skill names, MOBA items, and system messages often land as awkward or incorrect Vietnamese. Have a native Vietnamese gamer review in-context strings before ship.

Which Unity versions support com.unity.localization?

Unity 2021.3 LTS and later: 2022.x, 2023.x, and Unity 6. Install from Unity Registry via Package Manager. No additional setup steps are required beyond installing the package and opening Localization Settings to add your locales.

Does Vietnamese need right-to-left text support in TextMeshPro?

No. Vietnamese is a left-to-right language. It uses a Latin-derived script with tone diacritics stacked on vowels, not a right-to-left script. Standard TextMeshPro LTR layout works without any RTL configuration changes.

How do I test Vietnamese strings in the Unity Editor without a physical device?

Open Window > Asset Management > Localization Scene Controls, set the Active Locale to vi, and enable Track Changes. All LocalizedString components update live in the Editor, so you can review string fit and diacritics without a device.

Should I use vi or vi-VN as the Unity locale code?

Use vi. W3C i18n guidance is to keep BCP 47 tags as short as possible. There are no significant written-language differences between regional Vietnamese variants that require the vi-VN subtag for a game UI. Google Play also accepts vi as the standard store-listing language code for Vietnamese.

Sources

Official sources consulted for this article:

Dao Huy (Lucas)
Dao Huy (Lucas)
Graduate, University of Foreign Language Studies, University of Da Nang. Signs a certificate of accuracy on every certified translation (USCIS, IRCC).

Written by Dao Huy (Lucas), Vietnamese translator and localization specialist (English, Chinese and French into Vietnamese). See translation services →

Get QuoteWhatsApp