ZOA Localization

ILocalizationService

interface

The runtime surface: read strings, switch locale, register tables and content packs, and read composition diagnostics. Registered against FoundryServiceRegistry by the scene installer.

• string GetString(LocalizationKey key)
• string GetString(LocalizationKey key, LocaleId locale)
• string GetStringFormatted(LocalizationKey key, params object[] args)
• string GetMessage(LocalizationKey key, IReadOnlyDictionary<string, object> args)
• LocaleId GetActiveLocale() void SetActiveLocale(LocaleId locale)
• void RegisterTable(LocalizationTable table, LocalizationTableRegistrationOptions options)
• void RegisterLocaleInfo(LocaleInfo localeInfo) void RegisterFallback(LocaleId locale, LocaleId fallbackLocale)
• void RegisterContentPack(LocalizationContentPack contentPack, LocalizationConflictPolicy conflictPolicy, int priority = 0)
• bool UnregisterContentPack(string contentPackId)
• IEnumerable<LocalizationCompositionIssue> GetCompositionIssues()
• event Action<LocaleId> LocaleChanged event Action<LocaleId> TableRegistered

LocalizationService

service

The default implementation, which also implements ILocalizationFallbackResolver. Composes registered tables per locale, resolves through explicit and parent-locale fallbacks with cycle protection, and optionally persists the active locale through a preference provider.

ILocalizationFallbackResolver

interface

Resolution with provenance. Reports the value, which locale actually answered, and whether a fallback was used, so tooling can tell a real translation from a chain hit.

• bool Resolve(LocalizationKey key, LocaleId locale, out string value, out LocaleId resolvedLocale, out bool wasFallback)

LocalizationKey

struct

A case-insensitive hierarchical key, lowercased on construction, with implicit string conversion in both directions. Throws on null or whitespace rather than silently producing an empty key.

• string Value { get; }

LocaleId

struct

A case-insensitive locale code such as en-US or fr-FR, lowercased on construction. The parent-locale fallback trims at the dash.

• string Value { get; }

LocalizationTable

class

A per-locale dictionary of LocalizedEntry. Add writes an entry with its metadata; AddEntry takes a pre-built one. Each entry carries production metadata beyond the string, and both translator handoff and build gating read it.

• LocaleId LocaleId { get; } int Count { get; } IEnumerable<LocalizationKey> Keys { get; }
• void Add(LocalizationKey key, string value, bool isPlaceholder = false, string notes = null, string context = null, LocalizationReviewStatus reviewStatus = LocalizationReviewStatus.New, int? characterLimit = null, string screenshotPath = null)
• bool TryGet(LocalizationKey key, out LocalizedEntry entry)
• IEnumerable<LocalizedEntry> Entries { get; }

LocalizedEntry

struct

One row with its production metadata: value, placeholder flag, notes, translator context, review status, character limit, and a screenshot reference.

• LocalizationKey Key { get; } string Value { get; } bool IsPlaceholder { get; }
• string Notes { get; } string Context { get; }
• LocalizationReviewStatus ReviewStatus { get; } int? CharacterLimit { get; } string ScreenshotPath { get; }

LocalizedString

struct

The serializable reference dropped on MonoBehaviours and ScriptableObjects. Holds a key plus source text and context, and resolves in a fixed order: service translation, then source text, then the key.

• string Key; string SourceText; string Context;
• bool HasKey { get; }
• string Resolve(ILocalizationService service)
• string Resolve(ILocalizationService service, IReadOnlyDictionary<string, object> arguments)

LocalizationTableRegistrationOptions

class

The composition metadata for one registration. An omitted TableId gets a generated GUID and an omitted ContentPackId defaults to "base", so a casual registration still participates correctly.

• string TableId { get; } string ContentPackId { get; } string ContentPackVersion { get; }
• int Priority { get; } LocalizationConflictPolicy ConflictPolicy { get; } string NamespacePrefix { get; }

LocalizationConflictPolicy

enum

How same-locale duplicate keys resolve: Error rejects, WarnKeepFirst keeps the earlier value, WarnOverride takes the incoming one, and NamespacedOverride overrides only inside the configured namespace.

LocalizationContentPack

class

A DLC or campaign manifest: pack id, display name, version, its tables, an optional required DLC id, and the fallback edges it introduces. Registerable after boot and removable by id.

• string PackId { get; } string DisplayName { get; } string Version { get; } string RequiredDlcId { get; }
• IReadOnlyList<LocalizationTable> Tables { get; }
• IReadOnlyDictionary<LocaleId, LocaleId> Fallbacks { get; }

LocaleInfo

class

Metadata for a supported locale: display name, native name, right-to-left flag, and the explicit fallback locale that takes priority over parent-locale trimming.

• LocaleId Id { get; } string DisplayName { get; } string NativeName { get; }
• bool IsRightToLeft { get; } LocaleId? FallbackLocale { get; }

ILocalizationValidator

interface

Coverage analysis and production build gating over a set of tables.

• LocalizationValidationReport ValidateCoverage(IEnumerable<LocalizationTable> tables, LocaleId referenceLocale)
• LocalizationValidationReport ValidateBuildReadiness(IEnumerable<LocalizationTable> tables, LocalizationBuildValidationOptions options)

LocalizationValidationReport

class

The validation result: per-locale coverage percentages, missing keys per locale, placeholder entries, orphaned keys, and the production issues. PassesBuildGate is true only when the issue list is empty.

• IReadOnlyDictionary<LocaleId, float> CoverageByLocale { get; }
• IReadOnlyDictionary<LocaleId, IReadOnlyList<LocalizationKey>> MissingKeysByLocale { get; }
• IReadOnlyList<(LocaleId Locale, LocalizationKey Key)> PlaceholderEntries { get; }
• IReadOnlyList<(LocaleId Locale, LocalizationKey Key)> OrphanedKeys { get; }
• bool PassesBuildGate { get; }

LocalizationBuildValidationOptions

class

What the build gate requires: the reference locale, the locales that must ship, the reachable key set to measure against, and switches for approved translations and character limits.

• LocaleId ReferenceLocale { get; }
• IReadOnlyList<LocaleId> RequiredLocales { get; }
• IReadOnlyList<LocalizationKey> ReachableKeys { get; }
• bool RequireApprovedTranslations { get; } bool EnforceCharacterLimits { get; }

ILocalizationExchangeCodec

interface

Encodes and decodes a LocalizationDocument for translator handoff. LocalizationCsvCodec is the one shipped implementation.

• LocalizationExchangeFormat Format { get; }
• string Export(LocalizationDocument document, LocalizationExportOptions options)
• LocalizationDocument Import(string payload, LocalizationImportOptions options)

LocalizationExchangeCodecRegistry

class

Discovery for exchange formats. CreateDefault returns a registry supporting CSV only; XLIFF, PO, and Google Sheets report as unsupported until a project registers its own codec.

• static LocalizationExchangeCodecRegistry CreateDefault()
• IReadOnlyList<LocalizationExchangeFormat> GetSupportedFormats()
• bool TryGetCodec(LocalizationExchangeFormat format, out ILocalizationExchangeCodec codec)
• ILocalizationExchangeCodec GetRequiredCodec(LocalizationExchangeFormat format)

LocalizationDocument

class

The normalised transport shape sitting between tables and any codec. FromTables pairs a source table against target tables to produce one row per key and target locale.

• LocaleId SourceLocale { get; } string ContentPackId { get; }
• IReadOnlyList<LocalizationDocumentRow> Rows { get; }
• static LocalizationDocument FromTables(LocalizationTable sourceTable, IEnumerable<LocalizationTable> targetTables, string contentPackId = null)

LocalizationPseudolocalizer

class

Generates a pseudo table from a source table so layout QA can start before translations exist. Expands text by a configurable ratio and preserves placeholders and markup.

• LocalizationTable Generate(LocalizationTable source, PseudolocalizationOptions options = null)
• string Transform(string value, PseudolocalizationOptions options = null)

ZoaLocalizationAdapter

class

The UI Toolkit binder. Applies a set of element-name-to-key bindings and refreshes them on LocaleChanged and TableRegistered, so late DLC text updates live UI. Disposable, and unsubscribes on dispose.

• void Refresh()
• void Dispose()

ZoaLocalizedElementBinding

class

One declarative binding: an element name, a key, the target property, and optional message arguments. The target is Text, Tooltip, FieldLabel, or Value.

• string ElementName { get; } LocalizationKey Key { get; }
• ZoaLocalizedBindingTarget Target { get; }
• IReadOnlyDictionary<string, object> Arguments { get; }

ILocalizationPreferenceProvider

interface

Optional persistence bridge for the player's chosen locale. PlayerPrefsLocalizationPreferenceProvider is the shipped implementation; a project with its own profile system implements the two members instead.

• bool TryLoadLocale(out LocaleId locale)
• void SaveLocale(LocaleId locale)

LocalizationTableAsset

asset

The authoring asset for one locale's strings. Rows carry the full production metadata, and ToRuntimeTable materialises them, writing empty values as placeholders so the fallback resolver treats an untranslated row as missing rather than blank.

• Tools/ZOA/Localization/Localization Table
• string LocaleCode { get; } string TableName { get; }
• IReadOnlyList<SerializedLocalizationEntry> Entries { get; }
• LocaleId ToLocaleId()
• LocalizationTable ToRuntimeTable()

ZOALocalizationSceneInstaller

component

Scene-root bootstrap. Creates or reuses one ILocalizationService, registers its configured table assets with a shared content-pack id, priority, and conflict policy, optionally installs PlayerPrefs persistence, and applies an initial locale. Execution order -9000.

• ZOA/Localization/Localization Scene Installer
• ILocalizationService Service { get; }
• void EnsureRegistered()