From efc3e21530267d83e022b3f4dc268ac79719ba59 Mon Sep 17 00:00:00 2001 From: Oliver Hamlet Date: Wed, 11 Jun 2025 17:46:19 +0100 Subject: [PATCH] Improve docs for language values --- .../data_structures/localised_content.rst | 5 +++- cpp/include/loot/metadata/message_content.h | 25 +++++++++------- src/metadata/message.rs | 30 +++++++++++-------- 3 files changed, 35 insertions(+), 25 deletions(-) diff --git a/cpp/docs/metadata/data_structures/localised_content.rst b/cpp/docs/metadata/data_structures/localised_content.rst index 17179769..0d2a7add 100644 --- a/cpp/docs/metadata/data_structures/localised_content.rst +++ b/cpp/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/cpp/include/loot/metadata/message_content.h b/cpp/include/loot/metadata/message_content.h index ebabf765..b5498757 100644 --- a/cpp/include/loot/metadata/message_content.h +++ b/cpp/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( diff --git a/src/metadata/message.rs b/src/metadata/message.rs index 23341e40..c89badcd 100644 --- a/src/metadata/message.rs +++ b/src/metadata/message.rs @@ -58,7 +58,7 @@ impl MessageContent { } } - /// Set the language code to the given value. + /// Set the language to the given value. #[must_use] pub fn with_language(mut self, language: String) -> Self { self.language = language.into_boxed_str(); @@ -70,7 +70,7 @@ impl MessageContent { &self.text } - /// Get the text's language code. + /// Get the text's language. pub fn language(&self) -> &str { &self.language } @@ -90,18 +90,22 @@ impl std::default::Default for MessageContent { /// Choose a [MessageContent] object from those given in `content` based on the /// given `language`. /// -/// The locale or language code for the preferred language to select. Codes are -/// of the form `[language code]_[country code]`. +/// Language strings 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. /// /// * 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 language 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` value +/// is present, that content is returned. +/// * If the given `language` value 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` value has no country code and there is no exact +/// match but content for the 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 [Option] is returned. pub fn select_message_content<'a>( content: &'a [MessageContent], @@ -169,7 +173,7 @@ impl Message { /// Construct a [Message] with the given type and content. If more than one /// [MessageContent] object is given, one must use - /// the language code given by [MessageContent::DEFAULT_LANGUAGE]. + /// the language given by [MessageContent::DEFAULT_LANGUAGE]. pub fn multilingual( message_type: MessageType, content: Vec,