package core:text/i18n
Source

⌘K
Ctrl+K
or
/

    Overview

    The i18n package is flexible and easy to use.

    It has one call to get a translation: get, which the user can alias into something like T.

    get, referred to as T here, has a few different signatures. All of them will return the key if the entry can't be found in the active translation catalog.

    T(key) returns the translation of key. T(key, n) returns a pluralized translation of key according to value n.

    T(section, key) returns the translation of key in section. T(section, key, n) returns a pluralized translation of key in section according to value n.

    By default lookup take place in the global i18n.ACTIVE catalog for ease of use. If you want to override which translation to use, for example in a language preview dialog, you can use the following:

    T(key, n, catalog) returns the pluralized version of key from explictly supplied catalog. T(section, key, n, catalog) returns the pluralized version of key in section from explictly supplied catalog.

    If a catalog has translation contexts or sections, then omitting it in the above calls looks up in section "".

    The default pluralization rule is n != 1, which is to say that passing n == 1 (or not passing n) returns the singular form. Passing n != 1 returns plural form 1.

    Should a language not conform to this rule, you can pass a pluralizer procedure to the catalog parser. This is a procedure that maps an integer to an integer, taking a value and returning which plural slot should be used.

    You can also assign it to a loaded catalog after parsing, of course.

    Example: 
    import "core:fmt"
import "core:text/i18n"

T :: i18n.get

mo :: proc() {
	using fmt

	err: i18n.Error

	/*
		Parse MO file and set it as the active translation so we can omit `get`'s "catalog" parameter.
	*/
	i18n.ACTIVE, err = i18n.parse_mo(#load("translations/nl_NL.mo"))
	defer i18n.destroy()

	if err != .None { return }

	/*
		These are in the .MO catalog.
	*/
	println("-----")
	println(T(""))
	println("-----")
	println(T("There are 69,105 leaves here."))
	println("-----")
	println(T("Hellope, World!"))
	println("-----")
	// We pass 1 into `T` to get the singular format string, then 1 again into printf.
	printf(T("There is %d leaf.\n", 1), 1)
	// We pass 42 into `T` to get the plural format string, then 42 again into printf.
	printf(T("There is %d leaf.\n", 42), 42)

	/*
		This isn't in the translation catalog, so the key is passed back untranslated.
	*/
	println("-----")
	println(T("Come visit us on Discord!"))
}

qt :: proc() {
	using fmt

	err: i18n.Error

	/*
		Parse QT file and set it as the active translation so we can omit `get`'s "catalog" parameter.
	*/
	i18n.ACTIVE, err = i18n.parse_qt(#load("translations/nl_NL-qt-ts.ts"))
	defer i18n.destroy()

	if err != .None {
		return
	}

	/*
		These are in the .TS catalog. As you can see they have sections.
	*/
	println("--- Page section ---")
	println("Page:Text for translation =", T("Page", "Text for translation"))
	println("-----")
	println("Page:Also text to translate =", T("Page", "Also text to translate"))
	println("-----")
	println("--- installscript section ---")
	println("installscript:99 bottles of beer on the wall =", T("installscript", "99 bottles of beer on the wall"))
	println("-----")
	println("--- apple_count section ---")
	println("apple_count:%d apple(s) =")
	println("\t 1  =", T("apple_count", "%d apple(s)", 1))
	println("\t 42 =", T("apple_count", "%d apple(s)", 42))
}

    Types

    Error ¶
    Source

    Error :: enum int {
	// 		General return values.
	None                           = 0, 
	Empty_Translation_Catalog, 
	Duplicate_Key, 
	// 		Couldn't find, open or read file.
	File_Error, 
	// 		File too short.
	Premature_EOF, 
	// 		GNU Gettext *.MO file errors.
	MO_File_Invalid_Signature, 
	MO_File_Unsupported_Version, 
	MO_File_Invalid, 
	MO_File_Incorrect_Plural_Count, 
	// 		Qt Linguist *.TS file errors.
	TS_File_Parse_Error, 
	TS_File_Expected_Context, 
	TS_File_Expected_Context_Name, 
	TS_File_Expected_Source, 
	TS_File_Expected_Translation, 
	TS_File_Expected_NumerusForm, 
	Bad_Str, 
	Bad_Id, 
}
    Related Procedures With Returns

    Parse_Options ¶
    Source

    Parse_Options :: struct {
	merge_sections: bool,
}
    Related Procedures With Parameters
    Related Constants

    Section ¶
    Source

    Section :: map[string][]string

    Translation ¶
    Source

    Translation :: struct {
	k_v:       map[string]map[string][]string,
	// k_v[section][key][plural_form] = ...
	intern:    strings.Intern,
	pluralize: proc(number: int) -> int,
}
    Related Procedures With Parameters
    Related Procedures With Returns

    Constants

    DEFAULT_PARSE_OPTIONS ¶
    Source

    DEFAULT_PARSE_OPTIONS :: Parse_Options{merge_sections = false}

    MAX_PLURALS ¶
    Source

    MAX_PLURALS :: min(max(#config(ODIN_i18N_MAX_PLURAL_FORMS, 10), 1), 255)
     

    Allow between 1 and 255 plural forms. Default: 10.

    Variables

    ACTIVE ¶
    Source

    ACTIVE: ^Translation
     

    Currently active catalog.

    TS_XML_Options ¶
    Source

    TS_XML_Options: encoding_xml.Options = …

    Procedures

    destroy ¶
    Source

    destroy :: proc(catalog: ^Translation = ACTIVE, allocator := context.allocator) {…}
     

    Same for destroy:

    - destroy(), to clean up the currently active catalog catalog i18n.ACTIVE
- destroy(catalog), to clean up a specific catalog.

    get_by_section ¶
    Source

    get_by_section :: proc(section, key: string, number: int = 1, catalog: ^Translation = ACTIVE) -> (value: string) {…}
     

    Several ways to use:

    - get(section, key), which defaults to the singular form and i18n.ACTIVE catalog, or
- get(section, key, number), which returns the appropriate plural from the active catalog, or
- get(section, key, number, catalog) to grab text from a specific one.

    get_by_slot_by_section ¶
    Source

    get_by_slot_by_section :: proc(section, key: string, slot: int = 0, catalog: ^Translation = ACTIVE) -> (value: string) {…}
     

    Several ways to use:

    - get_by_slot(key), which defaults to the singular form and i18n.ACTIVE catalog, or
- get_by_slot(key, slot), which returns the requested plural from the active catalog, or
- get_by_slot(key, slot, catalog) to grab text from a specific one.

If a file format parser doesn't (yet) support plural slots, each of the slots will point at the same string.

    get_by_slot_single_section ¶
    Source

    get_by_slot_single_section :: proc(key: string, slot: int = 0, catalog: ^Translation = ACTIVE) -> (value: string) {…}
     

    Several ways to use:

    - get_by_slot(key), which defaults to the singular form and i18n.ACTIVE catalog, or
- get_by_slot(key, slot), which returns the requested plural from the active catalog, or
- get_by_slot(key, slot, catalog) to grab text from a specific one.

If a file format parser doesn't (yet) support plural slots, each of the slots will point at the same string.

    get_single_section ¶
    Source

    get_single_section :: proc(key: string, number: int = 1, catalog: ^Translation = ACTIVE) -> (value: string) {…}
     

    Several ways to use:

    - get(key), which defaults to the singular form and i18n.ACTIVE catalog, or
- get(key, number), which returns the appropriate plural from the active catalog, or
- get(key, number, catalog) to grab text from a specific one.

    parse_mo_file ¶
    Source

    parse_mo_file :: proc(filename: string, options: Parse_Options = DEFAULT_PARSE_OPTIONS, pluralizer: proc(_: int) -> int = nil, allocator := context.allocator) -> (translation: ^Translation, err: Error) {…}

    parse_mo_from_bytes ¶
    Source

    parse_mo_from_bytes :: proc(data: []u8, options: Parse_Options = DEFAULT_PARSE_OPTIONS, pluralizer: proc(_: int) -> int = nil, allocator := context.allocator) -> (translation: ^Translation, err: Error) {…}

    parse_qt_linguist_file ¶
    Source

    parse_qt_linguist_file :: proc(filename: string, options: Parse_Options = DEFAULT_PARSE_OPTIONS, pluralizer: proc(_: int) -> int = nil, allocator := context.allocator) -> (translation: ^Translation, err: Error) {…}

    parse_qt_linguist_from_bytes ¶
    Source

    parse_qt_linguist_from_bytes :: proc(data: []u8, options: Parse_Options = DEFAULT_PARSE_OPTIONS, pluralizer: proc(_: int) -> int = nil, allocator := context.allocator) -> (translation: ^Translation, err: Error) {…}

    read_u16 ¶
    Source

    read_u16 :: proc(data: []u8, native_endian: bool = true) -> (res: u16, err: Error) {…}

    read_u32 ¶
    Source

    read_u32 :: proc(data: []u8, native_endian: bool = true) -> (res: u32, err: Error) {…}
     

    Helpers.

    Procedure Groups

    get ¶
    Source

    get_by_slot ¶
    Source

    parse_mo ¶
    Source

    parse_mo :: proc{
	parse_mo_file,
	parse_mo_from_bytes,
}

    parse_qt ¶
    Source

    Source Files

    Generation Information

    Generated with odin version dev-2024-04 (vendor "odin") Windows_amd64 @ 2024-04-25 21:10:22.398684200 +0000 UTC