app.i18n - Internationalization API

Multi-language support and localization.

Permission: L0 Safe — always available, no declaration needed

Methods

app.i18n.t(key, args?, default?)

Gets translated text.

Parameters:

key (string) - Translation key
args (array, optional) - Interpolation arguments; placeholders are 0-based
default (string, optional) - Default value (returned when the key does not exist)

Returns: string - Translated text

-- Simple translation
local text = app.i18n.t("menu.title")

-- With parameters (**placeholders start at {0}**, not {1})
local text = app.i18n.t("file.count", {5})
-- In the translation file: "file.count": "{0} files in total"
-- Result: "5 files in total"

-- Multiple arguments fill {0} {1} {2} in order
local text = app.i18n.t("result.size", {"1.2 MB", "800 KB"})
-- In the translation file: "result.size": "Original {0}, compressed {1}"

-- With default value
local text = app.i18n.t("missing.key", nil, "Default text")

app.i18n.locale()

Gets the current locale.

Returns: string - Language code

local locale = app.i18n.locale()  -- "zh-Hans" or "en"

app.i18n.has(key)

Checks whether a translation key exists.

Parameters:

key (string) - Translation key

Returns: boolean

if app.i18n.has("custom.message") then
    local text = app.i18n.t("custom.message")
end

app.i18n.locales()

Gets the list of languages supported by the plugin.

Returns: array - Array of language codes

local locales = app.i18n.locales()
-- {"zh-Hans", "en"}

Translation File Format

Translation files are located in the locales/ subdirectory of the plugin directory, using JSON format:

locales/zh-Hans.json:

{
    "plugin.name": "Image Tools",
    "menu.compress": "Compress Images",
    "message.processing": "Processing {0}/{1}...",
    "message.complete": "Processed {0} files"
}

locales/en.json:

{
    "plugin.name": "Image Tools",
    "menu.compress": "Compress Images",
    "message.processing": "Processing {0}/{1}...",
    "message.complete": "Processed {0} files"
}

Examples

Plugin with Internationalization

function MyPlugin:handleCompress(context)
    local files = context.selectedFiles

    if #files == 0 then
        app.notification.show(
            app.i18n.t("plugin.name"),
            app.i18n.t("message.noFiles", nil, "Please select files")
        )
        return
    end

    for i, file in ipairs(files) do
        app.log.info(app.i18n.t("message.processing", {i, #files}))
        -- Process file...
    end

    app.notification.show(
        app.i18n.t("plugin.name"),
        app.i18n.t("message.complete", {#files})
    )
end