z_language (zotonic_core v1.0.0-rc.17)
Language code handling functions.
Mandatory background read on language tags: [1].
Some quotes from [1]:
The golden rule when creating language tags is to keep the tag as short as possible. Avoid region, script or other subtags except where they add useful distinguishing information. For instance, use 'ja' for Japanese and not 'ja-JP', unless there is a particular reason that you need to say that this is Japanese as spoken in Japan, rather than elsewhere.
The entries in the registry follow certain conventions with regard to upper and lower letter-casing. For example, language tags are lower case, alphabetic region subtags are upper case, and script tags begin with an initial capital. This is only a convention!
Note that we use lower case subtags in subtag identifiers and URLs.
Language identifiers can have the following forms: - language; - language-extlang; - language-region; - language-script; It is discouraged to use language-script-region, but it is possible if required. For a list of language, region and script codes, see [2]. [1] http://www.w3.org/International/articles/language-tags/ [2] http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry
Summary
Functions
List of language data. Returns a maps of language maps; sub-languages are added to the map of main languages. For each language a map with properties is returned - see properties/1. Each language is present with its iso code as an atom and binary key. This for easier lookups.
Fetch the available translations by checking for all .po files in zotonic_core
Returns the configured default language for this server; if not set, 'en' (English).
Return list of languages enabled in the user interface. This might be an empty list.
Get the list of configured languages that are editable. The list is in the order of configured priority, falls back to have at least one editable language
Return list of languges enabled in the user interface. This might be an empty list.
Get the list of configured languages that are enabled. The list is in the order of configured priority, falls back to have at least one enabled language.
Returns the English language name.
Return the list of fallback languages (atoms) for the language.
Return the fallback language (the base language); if no fallback language is found, returns the default language.
Initialize the i18n language configurations
Check if a language code is allowed to be edited. This is a superset of the enabled languages. Returns false for unknown languages.
Check if a language code is allowed to be used as a user selectable language for the interface. Returns false for unknown languages.
Check if the given language is a rtl language.
Check if the language code code is a valid language.
Get the list of configured languages.
Return the currently configured list of languages, falls back to have at least one enabled language.
Return the currently configured list of languages, sorted by the localized name.
Returns the local language name in the language itself.
Returns the language name in the current language.
Map of language data of main languages.
Returns a list of properties from a language item retrieved from *all* languages. Proplists key: language code - this is the ISO 639-1 language code or otherwise the ISO 639-3, combined with region or script extension (lowercase). Properties: - name: native language name. - name_en: English language name. - language: base language; functions as fallback language if translation is not available for the sub-language - region (only for region variations): Alpha-2 code of country/region (ISO 3166-2). - script (only for script variations): 4-letter script code (ISO 15924); if omitted: Latn. - direction: (if omitted: LTR) or RTL.
Save a new language config list. If the empty list is saved then the default language (en) is enabled. There must be a language enabled. The list is in the order of preference. The default system language is the first enabled (true) language in the list.
Sort a list of language codes by their localized name. If the value is a map then the property 'name_localized' is added. Always returns a proplist.
Translate a language-code to an atom; only return known codes. Also map aliased language codes to their preferred format. Eg. 'zh-tw' to 'zh-hant'
Types
-type language() :: language_code() | binary() | string().
-type language_code() :: atom().
-type language_status() :: true | editable | false.
Functions
-spec all_languages() -> LanguageMap when LanguageMap :: #{Code => map()}, Code :: binary() | atom().
List of language data. Returns a maps of language maps; sub-languages are added to the map of main languages. For each language a map with properties is returned - see properties/1. Each language is present with its iso code as an atom and binary key. This for easier lookups.
Fetch the available translations by checking for all .po files in zotonic_core
-spec default_language(OptContext) -> language_code() when OptContext :: z:context() | undefined.
Returns the configured default language for this server; if not set, 'en' (English).
-spec editable_language_codes(z:context()) -> [language_code()].
Return list of languages enabled in the user interface. This might be an empty list.
-spec editable_languages(Context) -> LanguageCodes when Context :: z:context(), LanguageCodes :: [language_code()].
Get the list of configured languages that are editable. The list is in the order of configured priority, falls back to have at least one editable language
-spec enabled_language_codes(z:context()) -> [language_code()].
Return list of languges enabled in the user interface. This might be an empty list.
-spec enabled_languages(Context) -> LanguageCodes when Context :: z:context(), LanguageCodes :: [language_code()].
Get the list of configured languages that are enabled. The list is in the order of configured priority, falls back to have at least one enabled language.
Returns the English language name.
-spec fallback_language(language()) -> [language_code()].
Return the list of fallback languages (atoms) for the language.
-spec fallback_language(language() | undefined, z:context()) -> language_code().
Return the fallback language (the base language); if no fallback language is found, returns the default language.
Initialize the i18n language configurations
Check if a language code is allowed to be edited. This is a superset of the enabled languages. Returns false for unknown languages.
-spec is_language_enabled(Language, Context) -> boolean() when Language :: language(), Context :: z:context().
Check if a language code is allowed to be used as a user selectable language for the interface. Returns false for unknown languages.
Check if the given language is a rtl language.
Check if the language code code is a valid language.
-spec language_config(Context) -> LanguageConfigList when Context :: z:context(), LanguageConfigList :: [{language_code(), language_status()}].
Get the list of configured languages.
-spec language_list(z:context()) -> [{language_code(), language_status()}].
Return the currently configured list of languages, falls back to have at least one enabled language.
-spec language_list_sorted(z:context()) -> [{language_code(), language_status()}].
Return the currently configured list of languages, sorted by the localized name.
Returns the local language name in the language itself.
Returns the language name in the current language.
-spec main_languages() -> map().
Map of language data of main languages.
Returns a list of properties from a language item retrieved from *all* languages. Proplists key: language code - this is the ISO 639-1 language code or otherwise the ISO 639-3, combined with region or script extension (lowercase). Properties: - name: native language name. - name_en: English language name. - language: base language; functions as fallback language if translation is not available for the sub-language - region (only for region variations): Alpha-2 code of country/region (ISO 3166-2). - script (only for script variations): 4-letter script code (ISO 15924); if omitted: Latn. - direction: (if omitted: LTR) or RTL.
-spec set_language_config(LanguageStatusList, Context) -> ok when Context :: z:context(), LanguageStatusList :: [{language_code(), language_status()}].
Save a new language config list. If the empty list is saved then the default language (en) is enabled. There must be a language enabled. The list is in the order of preference. The default system language is the first enabled (true) language in the list.
-spec sort_localized([language_code()], Context) -> [language_code()] when Context :: z:context(); ([{language_code(), language_status()}], Context) -> [{language_code(), language_status()}] when Context :: z:context(); ([{language_code(), map()}], Context) -> [{language_code(), map()}] when Context :: z:context(); ([map()], Context) -> [{language_code(), map()}] when Context :: z:context().
Sort a list of language codes by their localized name. If the value is a map then the property 'name_localized' is added. Always returns a proplist.
-spec to_language_atom(language()) -> {ok, language_code()} | {error, not_a_language}.
Translate a language-code to an atom; only return known codes. Also map aliased language codes to their preferred format. Eg. 'zh-tw' to 'zh-hant'