Skip to Content
defold-typescript libraries
Insality

Insality/defold-lang/lang

Localization helpers for Defold: string tables, pluralization, and locale fallback.

  • GitHub: Insality/defold-lang — pinned to 5
    1. This repo publishes no stable release. Pick a tag from Insality/defold-lang tags and add its Source code (zip) URL — for the pinned tag, https://github.com/Insality/defold-lang/archive/refs/tags/5.zip — to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as lang from "lang"

Functions

on_lang_changed()

Global callback after language is loaded and translations are ready. Called by set_lang, set_next_lang, and load_langs. Set once at startup to refresh UI.

init(available_langs: lang_data[], lang_on_start?: string | undefined)

Call this to initialize lang module

Parameters

  • available_langs: lang_data[] — List of { id = "en", path = "/locales/en.json" }
  • lang_on_start?: string | undefined — Language code to set on start, override saved language

load_langs(pack_id: string, langs: lang_data[], on_lang_changed?: ((...args: any[]) => unknown) | undefined)

Load additional locale pack and refresh current language

Parameters

  • pack_id: string — Pack id for future unload
  • langs: lang_data[] — List of { id = "en", path = "/locales/en.json" }
  • on_lang_changed?: ((...args: any[]) => unknown) | undefined

set_lang(lang_id: string, on_lang_changed?: ((...args: any[]) => unknown) | undefined)

Set current language

Parameters

  • lang_id: string — current language code (en, jp, ru, etc.)
  • on_lang_changed?: ((...args: any[]) => unknown) | undefined

set_next_lang(on_lang_changed?: ((...args: any[]) => unknown) | undefined): string

Set next language from lang list and return it's code

Parameters

  • on_lang_changed?: ((...args: any[]) => unknown) | undefined

Returns

  • string — The language code being switched to

get_next_lang(): string

Get next language from lang list and return it's code

Returns

  • string — next language code

get_lang(): string

Get current language

Returns

  • string — Current language code

get_langs(): string[]

Return list of available languages

Returns

  • string[] — List of available languages

txt(text_id: string): string

Get translation for text id

Parameters

  • text_id: string — text id from your localization

Returns

  • string — ("ui_hello_world") -> "Hello, World!"

txp(text_id: string, ...args: (string | number)[]): string

Get translation for text id with params

Parameters

  • text_id: string — Text id from your localization
  • ...args: string | number — Params for translation

Returns

  • string — ("ui_hello_name", "John") -> "Hello, John!"

txr(text_id: string): string

Get random translation for text id, split by \n symbol

Parameters

  • text_id: string — text id from your localization

Returns

  • string — ("ui_hint") -> "Hint 1" or "Hint 2" or ...

is_exist(text_id: string): boolean

Check is translation with text_id exist

Parameters

  • text_id: string — text id from your localization

Returns

  • boolean — Is translation exist for text_id

set_logger(logger_instance?: lang_logger | LuaTable | undefined)

Set logger for lang module. Pass nil to use empty logger

Parameters

  • logger_instance?: lang_logger | LuaTable | undefined

reset_state()

Reset module lang state

get_state(): lang_state

Get lang module state

Returns

  • lang_state

set_state(state: lang_state)

Set lang module state

Parameters

  • state: lang_state

get_default_lang(): string

Get default language

Returns

  • string — Default language code

get_lang_table(): LuaTable<string, string>

Get current lang table { key = "value" }

Returns

  • LuaTable<string, string>

is_lang_available(lang_id: string): boolean

Check if language is available

Parameters

  • lang_id: string — Language code to check

Returns

  • boolean — True if language is available

Types

lang_logger

lang_logger.trace: (_: unknown, msg: string, data: unknown) => void

lang_logger.debug: (_: unknown, msg: string, data: unknown) => void

lang_logger.info: (_: unknown, msg: string, data: unknown) => void

lang_logger.warn: (_: unknown, msg: string, data: unknown) => void

lang_logger.error: (_: unknown, msg: string, data: unknown) => void

lang

lang.state: lang_state

lang.on_lang_changed: (...args: any[]) => unknown

Called after translations are loaded

lang_state

lang_state.lang: string

current language name (en, jp, ru, etc.)

lang_data

lang_data.path: string | LuaTable | undefined

Lua table, json or csv path, ex: "/resources/lang/en.json", "/resources/lang/en.csv"

lang_data.id: string

Language code, ex: "en". If csv file, it's a header name

lang_data.loader: ((...args: any[]) => unknown) | undefined

Optional async loader function with signature: loader(path, on_success, on_error)

On this page