classDocs / FluentBundle

FluentBundle

classsharedsource

Object → FluentBundle

The collection of messages of one locale, formats them with variables.

lua

local bundle = fluent.Bundle( "ru" )
bundle:addResource( file_content )

local errors = {}
print( bundle:format( "items", { count = 3 }, errors ) ) -- 3 предмета

Constructor

FluentBundle(locales: ( string | string[] ), options: fluent.BundleOptions?): FluentBundle

Fields

Name	Type	Description
`locales`	`string[]`	The locale tags, the first one is used for formatting.
`locale`	`fluent.Locale`	The formatting data of the first locale.
`messages`	`table<string, fluent.Message>`	The messages by their identifiers.
`terms`	`table<string, fluent.Message>`	The terms by their identifiers, with `-`.
`functions`	`table<string, fluent.Function>`	The functions available to messages.
`use_isolating`	`boolean`	If `true`, placeables are wrapped in Unicode bidi isolation marks.
`transform`	`( fun( text: string ): string ) \| nil`	The function applied to every text element.

Methods

`addResource`	Adds the messages and terms of the resource to the bundle.
`format`	Formats the message value, or its attribute if the identifier is message.attribute.
`formatPattern`	Formats the pattern of a message or its attribute.
`getMessage`	Returns the message, its value and attributes patterns are formatted with FluentBundle:formatPattern.
`hasMessage`	Checks if the bundle has the message, terms are not messages.
`setFunction`	Adds or replaces the function available to messages.

#FluentBundle:addResource

sharedsource

function FluentBundle:addResource(resource: FluentResource | string, allow_overrides?: boolean): string[]

Adds the messages and terms of the resource to the bundle.

Parameters

Name	Type	Description
`resource`	`FluentResource \| string`	The resource or the FTL source to parse.
`allow_overrides`optional	`boolean`	If `true`, existing messages and terms are replaced, otherwise they are kept and reported.

Returns

Type	Name	Description
`string[]`	`errors`	The override errors, syntax errors of a parsed source are in `FluentResource.errors`.

#FluentBundle:format

sharednodiscardsource

function FluentBundle:format(id: string, args?: table<string, fluent.Argument>, errors?: Error[]): string | nil

Formats the message value, or its attribute if the identifier is message.attribute.

Parameters

Name	Type	Description
`id`	`string`	The message identifier, e.g. `"login-input"` or `"login-input.placeholder"`.
`args`optional	`table<string, fluent.Argument>`	The variables.
`errors`optional	`Error[]`	The list collecting the errors, see `FluentBundle:formatPattern`.

Returns

Type	Name	Description
`string \| nil`	`str`	The formatted string, `nil` if the message or its attribute does not exist.

#FluentBundle:formatPattern

sharednodiscardsource

function FluentBundle:formatPattern(pattern: fluent.Pattern, args?: table<string, fluent.Argument>, errors?: Error[]): string

Formats the pattern of a message or its attribute.

If errors is given, errors are collected into it and the best possible string is returned, e.g. {$name} for a missing variable, otherwise the first error is thrown.

lua

local message = bundle:getMessage( "hello" )
if message ~= nil and message.value ~= nil then
    local errors = {}
    print( bundle:formatPattern( message.value, { name = "World" }, errors ) )
end

Parameters

Name	Type	Description
`pattern`	`fluent.Pattern`	The pattern to format.
`args`optional	`table<string, fluent.Argument>`	The variables.
`errors`optional	`Error[]`	The list collecting the errors.

Returns

Type	Name	Description
`string`	`str`	The formatted string.

#FluentBundle:getMessage

sharednodiscardsource

function FluentBundle:getMessage(id: string): fluent.Message | nil

Returns the message, its value and attributes patterns are formatted with FluentBundle:formatPattern.

Parameters

Name	Type	Description
`id`	`string`	The message identifier.

Returns

Type	Name	Description
`fluent.Message \| nil`	`message`	The message, `nil` if it does not exist.

#FluentBundle:hasMessage

sharednodiscardsource

function FluentBundle:hasMessage(id: string): boolean

Checks if the bundle has the message, terms are not messages.

Parameters

Name	Type	Description
`id`	`string`	The message identifier.

Returns

Type	Name	Description
`boolean`	`has_message`	`true` if the message exists.

#FluentBundle:setFunction

sharedsource

function FluentBundle:setFunction(name: string, fn: fluent.Function | nil)

Adds or replaces the function available to messages.

lua

bundle:setFunction( "UPPER", function( positional )
    return string.upper( tostring( positional[ 1 ] ) )
end )

Parameters

Name	Type	Description
`name`	`string`	The function name, must be upper-case to be callable from FTL.
`fn`	`fluent.Function \| nil`	The function, `nil` removes it.