Struct L10N

pub struct L10N;

Localization service.

Implementations

impl L10N

pub fn load(&self, source: impl L10nSource)

Change the localization resources to source.

All active variables and handles will be updated to use the new source.

pub fn load_dir(&self, dir: impl Into<PathBuf>)

Start watching the dir for dir/{lang}/*.ftl and dir/{lang}/deps/*/*/*.ftl files.

The available_langs variable maintains an up-to-date list of locale files found, the files are only loaded when needed, and also are watched to update automatically.

pub fn available_langs( &self, ) -> BoxedVar<Arc<LangMap<HashMap<LangFilePath, PathBuf>>>>

Available localization files.

The value maps lang to one or more files, the files can be from the project dir/{lang}/{file}.ftl or from dependencies dir/{lang}/deps/{pkg-name/{pkg-version}/{file}.ftl.

Note that this map will include any file in the source dir that has a name that is a valid lang!, that includes the template.ftl file and test pseudo-locales such as qps-ploc.ftl.

pub fn available_langs_status(&self) -> BoxedVar<LangResourceStatus>

Status of the available_langs list.

This will be NotAvailable before the first call to load_dir, then it changes to Loading, then Loaded or Error.

Note that this is the status of the resource list, not of each individual resource, you can use LangResource::status for that.

pub async fn wait_available_langs(&self)

Waits until available_langs_status is not Loading.

pub fn app_lang(&self) -> ArcCowVar<Langs, ArcVar<Langs>>

Gets a read-write variable that sets the preferred languages for the app. Lang not available are ignored until they become available, the first language in the vec is the most preferred.

The value is the same as sys_lang, if set the variable disconnects from system lang.

Note that the LANG_VAR is used in message requests, the default value of that context variable is this one.

pub fn sys_lang(&self) -> ReadOnlyArcVar<Langs>

Gets a read-only variable that is the current system language.

The variable will update when the view-process notifies that the config has changed. Is empty if the system locale cannot be retrieved.

pub fn message( &self, file: impl Into<LangFilePath>, id: impl Into<Txt>, attribute: impl Into<Txt>, fallback: impl Into<Txt>, ) -> L10nMessageBuilder

Gets a read-only variable that is a localized message in the localization context where the variable is first used. The variable will update when the contextual language changes.

If the message has variable arguments they must be provided using L10nMessageBuilder::arg, the returned variable will also update when the arg variables update.

Prefer using the l10n! macro instead of this method, the macro does compile time validation.

Params

• file: Name of the resource file, in the default directory layout the file is searched at dir/{lang}/{file}.ftl, if empty the file is searched at dir/{lang}/_.ftl. Only a single file name is valid, no other path components allowed. Note that the file can also be a full LangFilePath that includes dependency package info. Those files are searched in dir/{lang}/deps/{pkg-name}/{pkg-version}/{file}.ftl.
• id: Message identifier inside the resource file.
• attribute: Attribute of the identifier, leave empty to not use an attribute.
• fallback: Message to use when a localized message cannot be found.

The id and attribute is only valid if it starts with letter [a-zA-Z], followed by any letters, digits, _ or - [a-zA-Z0-9_-]*.

Panics if any parameter is invalid.

pub fn lang_resource( &self, lang: impl Into<Lang>, file: impl Into<LangFilePath>, ) -> LangResource

Gets a handle to the lang file resource.

The resource will be loaded and stay in memory until all clones of the handle are dropped, this can be used to pre-load resources so that localized messages find it immediately avoiding flashing the fallback text in the UI.

If the resource directory or file changes it is auto-reloaded, just like when a message variable held on the resource does.

Params

• lang: Language identifier.
• file: Name of the resource file, in the default directory layout the file is searched at dir/{lang}/{file}.ftl, if empty the file is searched at dir/{lang}/_.ftl. Only a single file name is valid, no other path components allowed. Note that the file can also be a full LangFilePath that includes dependency package info. Those files are searched in dir/{lang}/deps/{pkg-name}/{pkg-version}/{file}.ftl.

Panics if the file is invalid.

pub async fn wait_lang(&self, lang: impl Into<Lang>) -> LangResources

Gets a handle to all resource files for the lang after they load.

This awaits for the available langs to load, then collect an awaits for all lang files.

pub async fn wait_first( &self, langs: impl Into<Langs>, ) -> (Option<Lang>, LangResources)

Gets a handle to all resource files of the first lang in langs that is available and loaded.

This awaits for the available langs to load, then collect an awaits for all lang files.

pub fn bind_command_meta( &self, file: impl Into<LangFilePath>, cmd: Command, meta_name: impl Into<Txt>, meta_value: CommandMetaVar<Txt>, )

Bind the command metadata to a message.

This is automatically called by command! instances that set the metadata l10n!: true or l10n!: "file".