libraryDocs / fluent

fluent

librarysharedsource

A port of Project Fluent, the localization system, based on @fluent/bundle.

lua

local resource = fluent.Resource( [[
-brand = Dreamwork
welcome = Welcome to { -brand }, { $name }!
files = { $count ->
    [one] { $count } file
   *[other] { $count } files
}
]] )

local bundle = fluent.Bundle( "en-US" )
bundle:addResource( resource )

print( bundle:format( "welcome", { name = "Player" } ) ) -- Welcome to Dreamwork, Player!
print( bundle:format( "files", { count = 1500 } ) ) -- 1,500 files

Classes & types

type

fluent.BundleOptions

The options of FluentBundle.

type

fluent.DateTimeOptions

The options of fluent.DateTime and DATETIME, a subset of Intl.DateTimeFormat options.

type

fluent.FunctionReference

The function call, FUNCTION( $value, name: "value" ).

The formatting data of the locale.

type

fluent.Message

The message or the term.

type

fluent.MessageReference

The message reference, message or message.attribute.

type

fluent.NamedArgument

The named argument, name: "value" or name: 1.

type

fluent.NumberLiteral

The number literal, -1.50.

type

fluent.NumberOptions

The options of fluent.Number and NUMBER, a subset of Intl.NumberFormat options.

type

fluent.Scope

The state of the single FluentBundle:formatPattern call, passed to FluentType:toString.

type

fluent.SelectExpression

The select expression, { $count -> [one] ... *[other] ... }.

type

fluent.StringLiteral

The string literal, "text".

type

fluent.TermReference

The term reference, -term, -term.attribute or -term( name: "value" ).

type

fluent.VariableReference

The variable reference, $name.

type

fluent.Variant

The variant of the select expression, [key] value.

Fields

Name	Type	Description
`locales`	`table<string, fluent.Locale>`	The registered locales by their normalized tags.
`builtins`	`table<string, fluent.Function>`	The built-in functions available to every bundle, `NUMBER` and `DATETIME`.

Functions

`fluent.formatDateTime`	Formats the Unix timestamp like Intl.DateTimeFormat, see fluent.DateTimeOptions.
`fluent.formatNumber`	Formats the number like Intl.NumberFormat.
`fluent.getLocale`	Returns the formatting data of the locale.
`fluent.isType`	Checks if the value is a Fluent type ( fluent.None, fluent.Number, fluent.DateTime or a custom one ).
`fluent.normalizeTag`	Normalizes the BCP 47 locale tag, en_us -> en-US, zh-hant-tw -> zh-Hant-TW.
`fluent.pluralCategory`	Returns the plural category of the number like Intl.PluralRules.
`fluent.setLocale`	Registers the formatting data of the locale, missing fields are taken from the parent locale.

#fluent.formatDateTime

sharednodiscardsource

function fluent.formatDateTime(timestamp: number, options?: fluent.DateTimeOptions, locale?: ( fluent.Locale | string )?): string

Formats the Unix timestamp like Intl.DateTimeFormat, see fluent.DateTimeOptions.

lua

print( fluent.formatDateTime( 905989690, { dateStyle = "long", timeZone = "UTC" }, "en" ) ) -- September 16, 1998
print( fluent.formatDateTime( 905989690, { dateStyle = "short", timeStyle = "short", timeZone = "UTC" }, "ru" ) ) -- 16.09.1998, 23:48

Parameters

Name	Type	Description
`timestamp`	`number`	The Unix timestamp in seconds.
`options`optional	`fluent.DateTimeOptions`	The formatting options.
`locale`optional	`( fluent.Locale \| string )?`	The locale or its tag, the root locale by default.

Returns

Type	Name	Description
`string`	`str`	The formatted date and time.

#fluent.formatNumber

sharednodiscardsource

function fluent.formatNumber(value: number, options?: fluent.NumberOptions, locale?: ( fluent.Locale | string )?): string

Formats the number like Intl.NumberFormat.

lua

print( fluent.formatNumber( 1234.5, { minimumFractionDigits = 2 }, "en" ) ) -- 1,234.50
print( fluent.formatNumber( 0.25, { style = "percent" }, "ru" ) ) -- 25 %
print( fluent.formatNumber( 9.99, { style = "currency", currency = "EUR" }, "de" ) ) -- 9,99 €

Parameters

Name	Type	Description
`value`	`number`	The number to format.
`options`optional	`fluent.NumberOptions`	The formatting options.
`locale`optional	`( fluent.Locale \| string )?`	The locale or its tag, the root locale by default.

Returns

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

#fluent.getLocale

sharednodiscardsource

function fluent.getLocale(tag: string): fluent.Locale

Returns the formatting data of the locale.

Subtags are removed one by one until a registered locale is found, pt-BR -> pt, the data of unknown languages uses ISO dates and the other plural category only.

Parameters

Name	Type	Description
`tag`	`string`	The BCP 47 locale tag, e.g. `"pt-BR"`, `"zh-Hant-TW"`.

Returns

Type	Name	Description
`fluent.Locale`	`locale`	The locale data.

#fluent.isType

sharednodiscardsource

function fluent.isType(value: any): boolean

Checks if the value is a Fluent type ( fluent.None, fluent.Number, fluent.DateTime or a custom one ).

Parameters

Name	Type	Description
`value`	`any`	The value to check.

Returns

Type	Name	Description
`boolean`	`is_type`	`true` if the value inherits `fluent.Type`.

#fluent.normalizeTag

sharednodiscardsource

function fluent.normalizeTag(tag: string): string

Normalizes the BCP 47 locale tag, en_us -> en-US, zh-hant-tw -> zh-Hant-TW.

Parameters

Name	Type	Description
`tag`	`string`	The locale tag.

Returns

Type	Name	Description
`string`	`normalized_tag`	The normalized tag.

#fluent.pluralCategory

sharednodiscardsource

function fluent.pluralCategory(value: number, options?: fluent.NumberOptions, locale?: ( fluent.Locale | string )?): fluent.Category

Returns the plural category of the number like Intl.PluralRules.

The fraction and significant digits options affect the category, 1.0 is other in English.

Parameters

Name	Type	Description
`value`	`number`	The number.
`options`optional	`fluent.NumberOptions`	The digits options and the rule `type`.
`locale`optional	`( fluent.Locale \| string )?`	The locale or its tag, the root locale by default.

Returns

Type	Name	Description
`fluent.Category`	`category`	The plural category.

#fluent.setLocale

sharedsource

function fluent.setLocale(tag: string, data: table, parent?: string): fluent.Locale

Registers the formatting data of the locale, missing fields are taken from the parent locale.

lua

fluent.setLocale( "uk", {
    months = { "січня", "лютого", ... },
    date = { short = "{dd}.{MM}.{y}", long = "{d} {MMMM} {y} р." }
}, "ru" )

Parameters

Name	Type	Description
`tag`	`string`	The BCP 47 locale tag.
`data`	`table`	The locale data, see `fluent.Locale`, becomes the locale object.
`parent`optional	`string`	The tag of the parent locale, the root locale if `nil`.

Returns

Type	Name	Description
`fluent.Locale`	`locale`	The registered locale.