Skip to main content

InstanceLocaleLoader

Owns the lazy per-locale loading state for an instance-decoded JSONTranslator (a folder of per-locale JSON StringValues / ModuleScripts): which locales are available, which have already been loaded, and the accumulated entry lookup.

Decodes and writes a locale's entries to the TranslatorService only the first time that locale is needed. Registered as a service by the JSONTranslator that owns it.

The locale files are reached through a TemplateProvider rather than off the folder directly. On a live server that keeps them from replicating to every client at join -- a game with a dozen languages otherwise ships all of them to a player who reads one -- and each file is fetched on demand instead. Off a live server the provider resolves them locally and synchronously, so nothing about loading changes there.

One file per locale. A second file resolving to a locale the provider already knows is warned about and ignored, since the provider keys templates by name.

Functions​

new​

</>
InstanceLocaleLoader.new(
translatorName: string,
sourceLocaleId: string,--

always loaded, the fallback for every key

folder: Instance--

holds the per-locale StringValue/ModuleScript children

) → InstanceLocaleLoader

Constructs a new InstanceLocaleLoader. Register it on the ServiceBag that provides the TranslatorService its writes land on -- it pulls in a TemplateProvider of its own, so the standard initialization chain has to reach it.

Init​

</>
InstanceLocaleLoader.Init(
serviceBag: ServiceBag
) → ()

Initializes the loader. Should be done via ServiceBag.

LoadSourceLocale​

</>
InstanceLocaleLoader.LoadSourceLocale(self: InstanceLocaleLoader) → ()

Loads the source locale. Always call this first -- it establishes the Source/Context that other locales' values merge onto, and it is the ultimate fallback for every key.

PromiseSourceLocale​

</>
InstanceLocaleLoader.PromiseSourceLocale(self: InstanceLocaleLoader) → Promise<()>

Resolves once the source locale's file has been fetched, decoded, and queued onto the TranslatorService. This is what makes a synchronous read (JSONTranslator.FormatByKey) safe: on a live client the file arrives over the network, so there is a window at boot where the fallback for every key is simply not here yet.

LoadAllLocales​

</>
InstanceLocaleLoader.LoadAllLocales(self: InstanceLocaleLoader) → ()

Loads every available locale file. Used off the client, where there is no single target locale to narrow to.

PromiseAllLocales​

</>
InstanceLocaleLoader.PromiseAllLocales(self: InstanceLocaleLoader) → Promise<()>

See InstanceLocaleLoader.LoadAllLocales. Resolves once every locale known at the time of the call has landed.

LoadLocale​

</>
InstanceLocaleLoader.LoadLocale(
localeId: string--

the target locale

) → ()

Loads every available locale file that shares the target's language (e.g. for "es-mx": both es and es-mx; for "fr-fr": every fr-* file), so a regional player gets the universal-language strings and same-language siblings as fallbacks before dropping to the source. The source locale is ensured first. Idempotent -- a file already loaded is never fetched, decoded, or written again -- and returns nothing, since the caller does not (and should not) care which files it touched.

PromiseLoadLocale​

</>
InstanceLocaleLoader.PromiseLoadLocale(
localeId: string
) → Promise<()>

See InstanceLocaleLoader.LoadLocale. Resolves once the files known to match the target at the time of the call have landed. Files that replicate in later are still loaded -- the request is remembered -- but this promise does not wait for them, since there is no point at which the set is known to be complete.

Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Constructs a new [InstanceLocaleLoader]. Register it on the [ServiceBag] that provides\nthe [TranslatorService] its writes land on -- it pulls in a [TemplateProvider] of its\nown, so the standard initialization chain has to reach it.",
            "params": [
                {
                    "name": "translatorName",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "sourceLocaleId",
                    "desc": "always loaded, the fallback for every key",
                    "lua_type": "string"
                },
                {
                    "name": "folder",
                    "desc": "holds the per-locale StringValue/ModuleScript children",
                    "lua_type": "Instance"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "InstanceLocaleLoader"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 77,
                "path": "src/clienttranslator/src/Shared/Loaders/InstanceLocaleLoader.lua"
            }
        },
        {
            "name": "Init",
            "desc": "Initializes the loader. Should be done via [ServiceBag].",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "InstanceLocaleLoader"
                },
                {
                    "name": "serviceBag",
                    "desc": "",
                    "lua_type": "ServiceBag"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 101,
                "path": "src/clienttranslator/src/Shared/Loaders/InstanceLocaleLoader.lua"
            }
        },
        {
            "name": "LoadSourceLocale",
            "desc": "Loads the source locale. Always call this first -- it establishes the Source/Context\nthat other locales' values merge onto, and it is the ultimate fallback for every key.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "InstanceLocaleLoader"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 129,
                "path": "src/clienttranslator/src/Shared/Loaders/InstanceLocaleLoader.lua"
            }
        },
        {
            "name": "PromiseSourceLocale",
            "desc": "Resolves once the source locale's file has been fetched, decoded, and queued onto the\n[TranslatorService]. This is what makes a synchronous read\n([JSONTranslator.FormatByKey]) safe: on a live client the file arrives over the network,\nso there is a window at boot where the fallback for every key is simply not here yet.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "InstanceLocaleLoader"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<()>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 141,
                "path": "src/clienttranslator/src/Shared/Loaders/InstanceLocaleLoader.lua"
            }
        },
        {
            "name": "LoadAllLocales",
            "desc": "Loads every available locale file. Used off the client, where there is no single\ntarget locale to narrow to.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "InstanceLocaleLoader"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 149,
                "path": "src/clienttranslator/src/Shared/Loaders/InstanceLocaleLoader.lua"
            }
        },
        {
            "name": "PromiseAllLocales",
            "desc": "See [InstanceLocaleLoader.LoadAllLocales]. Resolves once every locale known at the time\nof the call has landed.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "InstanceLocaleLoader"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<()>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 159,
                "path": "src/clienttranslator/src/Shared/Loaders/InstanceLocaleLoader.lua"
            }
        },
        {
            "name": "LoadLocale",
            "desc": "Loads every available locale file that shares the target's language (e.g. for \"es-mx\":\nboth `es` and `es-mx`; for \"fr-fr\": every `fr-*` file), so a regional player gets the\nuniversal-language strings and same-language siblings as fallbacks before dropping to\nthe source. The source locale is ensured first. Idempotent -- a file already loaded is\nnever fetched, decoded, or written again -- and returns nothing, since the caller does\nnot (and should not) care which files it touched.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "InstanceLocaleLoader"
                },
                {
                    "name": "localeId",
                    "desc": "the target locale",
                    "lua_type": "string"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 179,
                "path": "src/clienttranslator/src/Shared/Loaders/InstanceLocaleLoader.lua"
            }
        },
        {
            "name": "PromiseLoadLocale",
            "desc": "See [InstanceLocaleLoader.LoadLocale]. Resolves once the files known to match the target\nat the time of the call have landed. Files that replicate in later are still loaded --\nthe request is remembered -- but this promise does not wait for them, since there is no\npoint at which the set is known to be complete.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "InstanceLocaleLoader"
                },
                {
                    "name": "localeId",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<()>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 192,
                "path": "src/clienttranslator/src/Shared/Loaders/InstanceLocaleLoader.lua"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "InstanceLocaleLoader",
    "desc": "Owns the lazy per-locale loading state for an instance-decoded [JSONTranslator]\n(a folder of per-locale JSON StringValues / ModuleScripts): which locales are\navailable, which have already been loaded, and the accumulated entry lookup.\n\nDecodes and writes a locale's entries to the [TranslatorService] only the first time\nthat locale is needed. Registered as a service by the [JSONTranslator] that owns it.\n\nThe locale files are reached through a [TemplateProvider] rather than off the folder\ndirectly. On a live server that keeps them from replicating to every client at join --\na game with a dozen languages otherwise ships all of them to a player who reads one --\nand each file is fetched on demand instead. Off a live server the provider resolves them\nlocally and synchronously, so nothing about loading changes there.\n\nOne file per locale. A second file resolving to a locale the provider already knows is\nwarned about and ignored, since the provider keys templates by name.",
    "source": {
        "line": 21,
        "path": "src/clienttranslator/src/Shared/Loaders/InstanceLocaleLoader.lua"
    }
}