Reference API Roblox

Engine API

Website

Related

Reference API Roblox

LocalizationTable

A LocalizationTable is a database of translations. It contains source strings and translations for various languages.

Member index 22

HistoryMember
731SourceLocaleId: string
731GetContents(): string
462GetEntries(): Array
731GetString(targetLocaleId: string, key: string): string
462GetTranslator(localeId: string): Instance
573RemoveEntry(key: string, source: string, context: string): null
573RemoveEntryValue(key: string, source: string, context: string, localeId: string): null
731RemoveKey(key: string): null
573RemoveTargetLocale(localeId: string): null
731SetContents(contents: string): null
573SetEntries(entries: Variant): null
731SetEntry(key: string, targetLocaleId: string, text: string): null
573SetEntryContext(key: string, source: string, context: string, newContext: string): null
573SetEntryExample(key: string, source: string, context: string, example: string): null
573SetEntryKey(key: string, source: string, context: string, newKey: string): null
573SetEntrySource(key: string, source: string, context: string, newSource: string): null
573SetEntryValue(key: string, source: string, context: string, localeId: string, text: string): null
573SetIsExemptFromUGCAnalytics(value: bool): null
inherited from Instance
731Archivable: bool
731Capabilities: SecurityCapabilities
731IsInSandbox: bool
731Name: string
731Parent: Instance
731PredictionMode: PredictionMode
731Sandboxed: bool
731UniqueId: UniqueId
576AddTag(tag: string): null
573ClearAllChildren(): null
462Clone(): Instance
573Destroy(): null
486FindFirstAncestor(name: string): Instance
486FindFirstAncestorOfClass(className: string): Instance
486FindFirstAncestorWhichIsA(className: string): Instance
486FindFirstChild(name: string, recursive: bool = false): Instance
486FindFirstChildOfClass(className: string): Instance
486FindFirstChildWhichIsA(className: string, recursive: bool = false): Instance
486FindFirstDescendant(name: string): Instance
563GetActor(): Actor
486GetAttribute(attribute: string): Variant
462GetAttributeChangedSignal(attribute: string): RBXScriptSignal
631GetAttributes(): Dictionary
648GetChildren(): Instances
462GetDebugId(scopeLength: int = 4): string
707GetDescendants(): Instances
486GetFullName(): string
706GetStyled(name: string, selector: string?): Variant
657GetStyledPropertyChangedSignal(property: string): RBXScriptSignal
576GetTags(): Array
576HasTag(tag: string): bool
486IsAncestorOf(descendant: Instance): bool
486IsDescendantOf(ancestor: Instance): bool
664IsPropertyModified(property: string): bool
698QueryDescendants(selector: string): Instances
573Remove(): null
576RemoveTag(tag: string): null
664ResetPropertyToDefault(property: string): null
573SetAttribute(attribute: string, value: Variant): null
462WaitForChild(childName: string, timeOut: double): Instance
731children(): Instances
731clone(): Instance
731destroy(): null
731findFirstChild(name: string, recursive: bool = false): Instance
731getChildren(): Instances
731isDescendantOf(ancestor: Instance): bool
731remove(): null
462AncestryChanged(child: Instance, parent: Instance)
462AttributeChanged(attribute: string)
462ChildAdded(child: Instance)
462ChildRemoved(child: Instance)
462DescendantAdded(descendant: Instance)
462DescendantRemoving(descendant: Instance)
500Destroying()
657StyledPropertiesChanged()
731childAdded(child: Instance)
inherited from Object
731ClassName: string
731className: string
647GetPropertyChangedSignal(property: string): RBXScriptSignal
647IsA(className: string): bool
731isA(className: string): bool
647Changed(property: string)

Description

A LocalizationTable is a database of translations. It contains source strings and translations for various languages. It is used with the Translator and LocalizationService auto-translator system to control text translations in the game. LocalizationTables are designed to be treated as resources, like a texture or a script. They are not optimized to be modified at runtime. Changing the contents of a table will cause the entire contents of the table to be replicated to all players.

LocalizationTable Entries

Each LocalizationTable contains a set of entries. Each entry contains the translations of the text, along with some special fields:

  • Key is an optional unique key for fast hash lookups in code. If it is non-empty it must be unique in the table.
  • Source is the original text in the source language that will be used by the LocalizationService automatic text replacement system to match GUI text and render a translation instead. The Source field can be filled by the text capture tools, or can be set manually. For key-based lookups the Source value can be used as a translation for LocalizationTable.SourceLocaleId if the entry doesn't have a translation for that locale. If Source is empty then the entry will not be used by the automatic replacement system.
  • Context is the full Instance name for the object that the text appeared on. Context is used for disambiguation by the automatic text replacement system. When multiple matches for the Source are found, the system will pick the best match by matching backwards from the end of the Context string. There are other more robust ways to handle disambiguation available as well, like using multiple tables with GuiBase2d.RootLocalizationTable.
  • Example is whatever you want it to be. If the text capture tool guessed some parameters for a string the Example field will contain an example of them used in context.

All of these fields are optional, but at least either Key or Source must be non-empty. No two entries can have the same Key, Source, and Context.

See Translating Dynamic Content for more information.

History 121

Members 22

GetContents

Parameters (0)
No parameters.
Returns (1)
string

Deprecated. Prefer LocalizationTable:GetEntries(), which returns the same data as a structured array of dictionaries. Returns all entries in the LocalizationTable encoded as a JSON-formatted string, the legacy serialized representation of the table's contents. Each entry is an object containing its key, context, examples, and source fields (each omitted when empty) along with a values map of locale IDs to translated strings.

This function is deprecated. It exists only for backward compatibility, and should not be used for new work. GetEntries should be used instead.

History 8

Tags: [Deprecated]

GetEntries

Parameters (0)
No parameters.
Returns (1)
Array

The GetEntries function returns an array of dictionaries contained in a given LocalizationTable, where each dictionary represents an entry of localization data.

To set the entries of a LocalizationTable, you can use LocalizationTable:SetEntries().

Each dictionary in the array contains the following fields:

IndexTypeDescription
KeystringA lookup key for this specific entry in the LocalizationTable.
SourcestringThe string used to format the localized string. Used as a lookup if a key is not provided.
ContextstringAn Instance:GetFullName() path to the object that was used to generate the LocalizationTable. Used as a lookup if a key is not provided.
ExamplestringThe string used to format the localization. Optional.
ValuesDictionaryA dictionary of language translations for this localization entry. The keys of this dictionary are locale ids, and the values are strings that are used to apply localization for the language corresponding to the locale id.

History 2

GetString

Parameters (2)
targetLocaleIdstring
keystring
Returns (1)
string

The GetString function returns a translation based on the specified language and key.

This function is deprecated. It exists only for backward compatibility, and should not be used for new work. GetTranslator should be used instead.

History 7

Tags: [Deprecated]

GetTranslator

Parameters (1)
localeIdstring
Returns (1)
Instance

Returns a Translator for entries in this LocalizationTable, in the specified language. The translator will first search in this table and then look in ancestor tables.

History 2

RemoveEntry

Parameters (3)
keystring
sourcestring
contextstring
Returns (1)
null

Removes an entry from the LocalizationTable, using the specified key, source, and context to narrow down the specific entry to be removed.

The entry is identified by the (key, source, context) triple. If key is non-empty it alone identifies the entry because keys are unique within the table. If key is empty the entry is matched by the (source, context) pair. When no matching entry exists the call is a silent no-op.

Removing an entry deletes all of its translations and metadata. To remove only a single locale's translation from an entry while keeping the entry itself, use LocalizationTable:RemoveEntryValue() instead.

History 3

RemoveEntryValue

Parameters (4)
keystring
sourcestring
contextstring
localeIdstring
Returns (1)
null

Removes a single language translation from the LocalizationTable, using the provided key, source, context, and localeId to narrow down the specific entry to be modified.

The entry is identified by the (key, source, context) triple (see LocalizationTable:RemoveEntry() for lookup rules). Once the entry is found, only the translation for localeId is erased; the entry itself and all other locale translations remain intact. The localeId is case-insensitive (it is canonicalized internally). If no matching entry exists, or the entry has no translation for localeId, the call is a silent no-op.

To remove the entire entry including all translations, use LocalizationTable:RemoveEntry(). To remove every translation of a given locale across all entries, use LocalizationTable:RemoveTargetLocale().

History 3

RemoveKey

Parameters (1)
keystring
Returns (1)
null

Deprecated in favor of LocalizationTable:RemoveEntry(). Calling RemoveKey is the same as making the following call to RemoveEntry:

This function is deprecated. It exists only for backward compatibility, and should not be used for new work. RemoveEntry should be used instead.

History 9

Tags: [Deprecated]

RemoveTargetLocale

Parameters (1)
localeIdstring
Returns (1)
null

Removes all translations from the LocalizationTable with the specified localeId.

This is a bulk operation that iterates every entry in the table and erases the translation for localeId from each one. Entries themselves are not removed even if they have no remaining translations after this call. To remove a single translation from one specific entry, use LocalizationTable:RemoveEntryValue() instead.

History 3

SetContents

Parameters (1)
contentsstring
Returns (1)
null

The SetContents function sets the contents of the LocalizationTable, via the legacy JSON format.

This function is deprecated. It exists only for backward compatibility, and should not be used for new work. SetEntries should be used instead.

History 9

Tags: [Deprecated]

SetEntries

Parameters (1)
entriesVariant
Returns (1)
null

Sets the contents of the LocalizationTable.

The entries parameter should be an array of dictionaries in the same format as the one returned from the LocalizationTable:GetEntries() function.

History 3

SetEntry

Parameters (3)
keystring
targetLocaleIdstring
textstring
Returns (1)
null

Deprecated. Prefer LocalizationTable:SetEntryValue() for matching an entry by key, source, and context, or LocalizationTable:SetEntries() to set many entries at once. Sets the translation text for the locale targetLocaleId on the LocalizationTable entry identified by key, creating a new entry with an empty source and context if no entry with that key exists. When targetLocaleId matches the table's LocalizationTable.SourceLocaleId, the entry's Source field is also set to text.

This function is deprecated. It exists only for backward compatibility, and should not be used for new work. SetEntryValue should be used instead.

History 10

Tags: [Deprecated]

SetEntryContext

Parameters (4)
keystring
sourcestring
contextstring
newContextstring
Returns (1)
null

Sets the Context field of a LocalizationTable entry to newContext, using the specified key, source, and context to narrow down the entry that will have this change applied.

The entry is identified by the (key, source, context) triple (see LocalizationTable:RemoveEntry() for lookup rules). If no matching entry exists, a new entry is created with the provided key, source, and newContext. The method throws an error if setting the new context would cause the entry to conflict with another existing entry that shares the same key, source, and context combination.

The Context field stores an Instance:GetFullName() path that the automatic text replacement system uses for disambiguation when multiple entries share the same Source string.

History 3

SetEntryExample

Parameters (4)
keystring
sourcestring
contextstring
examplestring
Returns (1)
null

Sets the Example field of a LocalizationTable entry to example, using the specified key, source, and context to narrow down the entry that will have this change applied.

The entry is identified by the (key, source, context) triple (see LocalizationTable:RemoveEntry() for lookup rules). If no matching entry exists, a new entry is created with the provided key, source, and context. The new example value always overwrites any existing example text on the entry.

The Example field is an arbitrary metadata string. The text-capture tools use it to store a sample of parameterized content in context, but developers may store any helpful annotation.

History 3

SetEntryKey

Parameters (4)
keystring
sourcestring
contextstring
newKeystring
Returns (1)
null

Sets the Key field of a LocalizationTable entry to newKey, using the specified key, source, and context to narrow down the entry that will have this change applied.

The entry is identified by the (key, source, context) triple (see LocalizationTable:RemoveEntry() for lookup rules). If no matching entry exists, a new entry is created with newKey, the provided source, and context. The method throws an error if newKey would conflict with an existing entry's key, because keys must be unique within the table. If newKey equals the entry's current key the call is a no-op.

The Key field is an optional unique identifier for fast hash lookups via Translator:FormatByKey(). When non-empty it must be unique across the entire table.

History 3

SetEntrySource

Parameters (4)
keystring
sourcestring
contextstring
newSourcestring
Returns (1)
null

Sets the Source field of a LocalizationTable entry to newSource, using the specified key, source, and context to narrow down the entry that will have this change applied.

The entry is identified by the (key, source, context) triple (see LocalizationTable:RemoveEntry() for lookup rules). If no matching entry exists, a new entry is created with the provided key, newSource, and context. The method throws an error if the resulting (key, newSource, context) combination would conflict with an existing entry. If newSource equals the entry's current source the call is a no-op.

The Source field is the original text in the source language used by the LocalizationService automatic text replacement system to match GUI text at runtime. Changing the source also recomputes the internal expression matcher, so parameterized format strings (e.g. {1:translate}) are re-parsed immediately.

History 3

SetEntryValue

Parameters (5)
keystring
sourcestring
contextstring
localeIdstring
textstring
Returns (1)
null

Sets the text of the specified localeId in a LocalizationTable entry, using the specified key, source, and context to narrow down the entry that will have this change applied.

The entry is identified by the (key, source, context) triple (see LocalizationTable:RemoveEntry() for lookup rules). If no matching entry exists, a new entry is created with the provided key, source, and context — this throws an error if both key and source are empty. The localeId is case-insensitive (it is canonicalized internally).

If text is non-empty the translation is stored (or replaced) for localeId on that entry. The text must be a valid format string (parameters like {1:translate} must be well-formed or the call throws). If text is an empty string the translation for localeId is removed from the entry, equivalent to calling LocalizationTable:RemoveEntryValue().

To set multiple entries at once, use LocalizationTable:SetEntries().

History 3

SetIsExemptFromUGCAnalytics

Parameters (1)
valuebool
Returns (1)
null

History 3

SourceLocaleId

TypeDefault
stringen-us

The Roblox locale of the input key strings for this table, for example "en-us" or "es-es." This is typically the "development language" of the game. For a Translator that merges multiple LocalizationTable objects, it's the LocaleId of the Default LocalizationTable. Defaults to "en-us".

History 7

Settings