From bee0f36d7be7e3d6bffd7bf1f79f205192dfe9f8 Mon Sep 17 00:00:00 2001 From: Oliver Hamlet Date: Wed, 11 Jun 2025 17:34:56 +0100 Subject: [PATCH] Improve docs for language values --- .../data_structures/localised_content.rst | 5 +++- include/loot/metadata/message_content.h | 25 +++++++++++-------- 2 files changed, 18 insertions(+), 12 deletions(-) diff --git a/docs/metadata/data_structures/localised_content.rst b/docs/metadata/data_structures/localised_content.rst index 17179769..0d2a7add 100644 --- a/docs/metadata/data_structures/localised_content.rst +++ b/docs/metadata/data_structures/localised_content.rst @@ -9,7 +9,10 @@ The localised content data structure is a key-value string map. .. describe:: lang - **Required.** The language that ``text`` is written in, given as a code of the form ``ll`` or ``ll_CC``, where ``ll`` is an ISO 639-1 language code and ``CC`` is an ISO 3166 country code. For example, + **Required.** The language that ``text`` is written in, given as an XPG-format + (a.k.a. POSIX-format) locale name of the form ``ll`` or ``ll_CC``, where + ``ll`` is an ISO 639-1 language code and ``CC`` is an ISO 3166 country code. + For example, ==================== ===== Language Code diff --git a/include/loot/metadata/message_content.h b/include/loot/metadata/message_content.h index ebabf765..b5498757 100644 --- a/include/loot/metadata/message_content.h +++ b/include/loot/metadata/message_content.h @@ -125,20 +125,23 @@ LOOT_API bool operator>=(const MessageContent& lhs, const MessageContent& rhs); * @param content * The MessageContent objects to choose between. * @param language - * The locale or language code for the preferred language to select. - * Locale codes are of the form `[language code]_[country code]`. + * The preferred language to select. Values are expected to have the + * form `[language code]` or `[language code]_[country code]`, where + * `[language code]` is an ISO 639-1 language code and `[country code]` + * is an ISO 3166 country code. * @return A MessageContent object. * * If the vector only contains a single element, that element is * returned. - * * If content with a language that exactly matches the given locale - * or language code is present, that content is returned. - * * If a locale code is given and there is no exact match but content - * for that locale's language is present, that content is returned. - * * If a language code is given and there is no exact match but - * content for a locale in that langauge is present, that content is - * returned. - * * If no locale or language code matches are found and content in - * the default language is present, that content is returned. + * * If content with a language that exactly matches the given language + * is present, that content is returned. + * * If the given language includes a country code and there is no exact + * match but content for the same language code is present, that + * content is returned. + * * If the given language does not include a country code and there is + * no exact match but content for thet same language code is present, + * that content is returned. + * * If no matches are found and content in the default language is + * present, that content is returned. * * Otherwise, an empty optional is returned. */ LOOT_API std::optional SelectMessageContent(