Skip to main content

TranslatorService

Handles selecting the right locale/translator for Studio, and Roblox games.

Functions​

SetForcedLocaleId​

</>
TranslatorService.SetForcedLocaleId(
localeId: string?
) → ()

Forces the locale id used for translation, overriding the inferred player/Roblox locale. Pass nil to clear the override and fall back to the inferred locale. Useful for an in-game language selector.

SetEntryValue​

</>
TranslatorService.SetEntryValue(
translationKey: string,
source: string,
context: string,
localeId: string,
text: string
) → ()

Queues a localization table entry value write. Writes are batched and flushed together at the end of the frame (via task.defer) instead of being applied synchronously, so a burst of translators loading does not each pay the cost of mutating (and re-replicating) the shared localization table in the load path.

Await TranslatorService.PromiseEntriesWritten before reading a translation to guarantee the pending writes have landed.

SetEntryExample​

</>
TranslatorService.SetEntryExample(
translationKey: string,
source: string,
context: string,
example: string
) → ()

Queues a localization table entry example write. See TranslatorService.SetEntryValue.

PromiseEntriesWritten​

</>
TranslatorService.PromiseEntriesWritten(self: TranslatorService) → Promise

Returns a promise that resolves once all currently-queued localization writes have been flushed to the table. Resolves immediately if nothing is pending.

Read paths should await this so translation never reads before the writes land.

FlushEntriesForTesting​

</>
TranslatorService.FlushEntriesForTesting(self: TranslatorService) → ()

Flushes every pending localization write synchronously. This defeats the end-of-frame batching and pays the full table write cost, so it exists for tests that need the table settled immediately. Production synchronous reads should use TranslatorService.FlushEntryForKey to land just the key they need.

FlushEntryForKey​

</>
TranslatorService.FlushEntryForKey(
translationKey: string
) → ()

Lands only what a synchronous read of a single key actually needs, leaving the rest of the batch queued for the normal end-of-frame flush. This lets a synchronous read (JSONTranslator.FormatByKey) guarantee the one key it reads is present without forcing -- and paying for -- the whole pending batch early.

Only the locales a read can actually consult are landed (the example and every other locale in the entry stay queued), so a read costs a handful of targeted writes rather than one per locale in the entry.

GetLocalizationWriteCount​

</>
TranslatorService.GetLocalizationWriteCount(self: TranslatorService) → number

Returns the total number of raw mutating calls made to the localization table. Each such call invalidates every AutoLocalize entry in the engine, so this is the cost we want to keep low. Primarily useful for diagnostics and regression tests.

ObserveTranslator​

</>
TranslatorService.ObserveTranslator(self: TranslatorService) → Observable<Translator>

Observes Roblox translator

PromiseTranslator​

</>
TranslatorService.PromiseTranslator(self: TranslatorService) → Observable<Translator>

Promises the Roblox translator

GetTranslator​

</>
TranslatorService.GetTranslator(self: TranslatorService) → Translator?

Gets the current translator to use

ObserveLocaleId​

</>
TranslatorService.ObserveLocaleId(self: TranslatorService) → Observable<string>

Observes the current locale id for this translator.

GetLocaleId​

</>
TranslatorService.GetLocaleId(self: TranslatorService) → string

Gets the localeId to use

Show raw api
{
    "functions": [
        {
            "name": "SetForcedLocaleId",
            "desc": "Forces the locale id used for translation, overriding the inferred player/Roblox\nlocale. Pass nil to clear the override and fall back to the inferred locale. Useful\nfor an in-game language selector.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TranslatorService"
                },
                {
                    "name": "localeId",
                    "desc": "",
                    "lua_type": "string?"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 117,
                "path": "src/clienttranslator/src/Shared/TranslatorService.lua"
            }
        },
        {
            "name": "SetEntryValue",
            "desc": "Queues a localization table entry value write. Writes are batched and flushed\ntogether at the end of the frame (via `task.defer`) instead of being applied\nsynchronously, so a burst of translators loading does not each pay the cost of\nmutating (and re-replicating) the shared localization table in the load path.\n\nAwait [TranslatorService.PromiseEntriesWritten] before reading a translation to\nguarantee the pending writes have landed.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TranslatorService"
                },
                {
                    "name": "translationKey",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "source",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "context",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "localeId",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "text",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 138,
                "path": "src/clienttranslator/src/Shared/TranslatorService.lua"
            }
        },
        {
            "name": "SetEntryExample",
            "desc": "Queues a localization table entry example write. See [TranslatorService.SetEntryValue].",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TranslatorService"
                },
                {
                    "name": "translationKey",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "source",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "context",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "example",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 159,
                "path": "src/clienttranslator/src/Shared/TranslatorService.lua"
            }
        },
        {
            "name": "PromiseEntriesWritten",
            "desc": "Returns a promise that resolves once all currently-queued localization writes\nhave been flushed to the table. Resolves immediately if nothing is pending.\n\nRead paths should await this so translation never reads before the writes land.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TranslatorService"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 204,
                "path": "src/clienttranslator/src/Shared/TranslatorService.lua"
            }
        },
        {
            "name": "FlushEntriesForTesting",
            "desc": "Flushes every pending localization write synchronously. This defeats the end-of-frame\nbatching and pays the full table write cost, so it exists for tests that need the table\nsettled immediately. Production synchronous reads should use\n[TranslatorService.FlushEntryForKey] to land just the key they need.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TranslatorService"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 218,
                "path": "src/clienttranslator/src/Shared/TranslatorService.lua"
            }
        },
        {
            "name": "FlushEntryForKey",
            "desc": "Lands only what a synchronous read of a single key actually needs, leaving the rest of\nthe batch queued for the normal end-of-frame flush. This lets a synchronous read\n([JSONTranslator.FormatByKey]) guarantee the one key it reads is present without forcing\n-- and paying for -- the whole pending batch early.\n\nOnly the locales a read can actually consult are landed (the example and every other\nlocale in the entry stay queued), so a read costs a handful of targeted writes rather\nthan one per locale in the entry.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TranslatorService"
                },
                {
                    "name": "translationKey",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 236,
                "path": "src/clienttranslator/src/Shared/TranslatorService.lua"
            }
        },
        {
            "name": "GetLocalizationWriteCount",
            "desc": "Returns the total number of raw mutating calls made to the localization table. Each\nsuch call invalidates every AutoLocalize entry in the engine, so this is the cost we\nwant to keep low. Primarily useful for diagnostics and regression tests.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TranslatorService"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 299,
                "path": "src/clienttranslator/src/Shared/TranslatorService.lua"
            }
        },
        {
            "name": "ObserveTranslator",
            "desc": "Observes Roblox translator",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TranslatorService"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Observable<Translator>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 409,
                "path": "src/clienttranslator/src/Shared/TranslatorService.lua"
            }
        },
        {
            "name": "PromiseTranslator",
            "desc": "Promises the Roblox translator",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TranslatorService"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Observable<Translator>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 418,
                "path": "src/clienttranslator/src/Shared/TranslatorService.lua"
            }
        },
        {
            "name": "GetTranslator",
            "desc": "Gets the current translator to use",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TranslatorService"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Translator?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 458,
                "path": "src/clienttranslator/src/Shared/TranslatorService.lua"
            }
        },
        {
            "name": "ObserveLocaleId",
            "desc": "Observes the current locale id for this translator.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TranslatorService"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Observable<string>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 467,
                "path": "src/clienttranslator/src/Shared/TranslatorService.lua"
            }
        },
        {
            "name": "GetLocaleId",
            "desc": "Gets the localeId to use",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "TranslatorService"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 514,
                "path": "src/clienttranslator/src/Shared/TranslatorService.lua"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "TranslatorService",
    "desc": "Handles selecting the right locale/translator for Studio, and Roblox games.",
    "source": {
        "line": 7,
        "path": "src/clienttranslator/src/Shared/TranslatorService.lua"
    }
}