diff --git a/utils.capnp b/utils.capnp index a5ec60b..c75bc8c 100644 --- a/utils.capnp +++ b/utils.capnp @@ -10,18 +10,25 @@ interface L10NString { get @0 ( lang :Text ) -> ( lang :Text, content :Text ); # Retrieve the string in the given locale. The input parameter MUST be a RFC5646-formatted # locale identifier (e.g: "en-US", "de-DE", "az-Arab-IR"). - # A server MUST set the outputs `lang` to the exact tag that the content it sends was written in - # and `content` to the localized string. - # If a server can't find a localized version it SHOULD try to substitute it. Substitution SHOULD - # only search for close matches, e.g. returning "en-UK" for a string requested in "en-US" or - # returning "es-ES" for a requested "es-VE". Substitution MUST NOT return a localization that an - # user can not be expected to understand unless the server has a priori knowledge that the user - # can read and understand said language. - # If a server sends a substituted string it MUST set the output `lang` to the tag of the - # substitute it is sending. - # If a server can't find a suitable substitute or is not doing substitution it MUST set the - # output `content` to a NULL pointer and set the output `lang` to the input `lang` it was - # passed. + # + # If a server can't find a localized version matching exactly it MUST try to substitute it. + # Substitution MUST always return more specific matches for general queries. + # e.g. if "it" is requested and the server has "it-CH" available it returns this string. + # + # Substitution SHOULD NOT cross language barriers, e.g. returning "en-GB" for a string requested + # in "cy-GB". Substitution MUST NOT return a localization in a different language unless server + # has a priori knowledge that the user can read and understand said language. + # + # Substitution SHOULD prefer unspecified subtags over wrong subtags. If "es-AR" is requested and a + # server has "es", and "es-VE" available, "es" should be selected. + # + # A server MUST set the output `lang` field to the exact tag that the content it sends was written + # in and `content` to the localized string. + # E.g. If a string is requested for "sr" and the server has found a string that was configured as + # "sr-Cyrl-BA" the server sets lang to "sr-Cyrl-BA". + # + # If a server can't find a suitable substitute it MUST set the output `content` to a NULL pointer + # and set the output `lang` to the input `lang` it was passed. # If a server can't parse a given `lang` tag it MUST set the output `lang` to a NULL pointer. available @1 () -> ( langs :List(Text) );