search

reconciliation-api / specs

Specifications of the reconciliation API
https://reconciliation-api.github.io/specs/draft/
30 stars 9 forks source link

I18n checklist: language #125

Open fsteeg opened 1 year ago

fsteeg commented 1 year ago

This is a self-review checklist based on the Internationalization Best Practices for Spec Developers.

(All lines seemed relevant for us here, I suggest we strikeout things that turn out not to be.)

See also issue #52, PR #108 and notes at https://etherpad.lobid.org/p/reconciliation-i18n.

Check marks indicate requirements that are fulfilled by this spec. Add comments to describe conformance.

Language basics

  1. [x] It should be possible to associate a language with any piece of localizable text or natural language content. more
    _Comments_gohere
  2. [x] Where possible, there should be a way to label natural language changes in inline text. more
    _Comments_gohere
  3. [x] Consider whether it is useful to express the intended linguistic audience of a resource, in addition to specifying the language used for text processing. more
    _Comments_gohere
  4. [x] A language declaration that indicates the text-processing language for a range of text must associate a single language value with a specific range of text. more
    _Comments_gohere
  5. [x] Use the HTML lang and XML xml:lang language attributes where appropriate to identify the text processing language, rather than creating a new attribute or mechanism. more
    _Comments_gohere
  6. [ ] It should be possible to associate a metadata-type language declaration (which indicates the intended use of the resource rather than the language of a specific range of text) with multiple language values. more
    _Comments_gohere
  7. [ ] Attributes that express the language of external resources should not use the HTML lang and XML xml:lang language attributes, but should use a different attribute when they represent metadata (which indicates the intended use of the resource rather than the language of a specific range of text). more
     I don't think we link to any external resources, so this should not apply to us

Defining language values

  1. [x] Values for language declarations must use BCP 47. more
    _Comments_gohere
  2. [x] Refer to BCP 47, not to its constituent parts, such as RFC 5646 or RFC 4647. more
    _Comments_gohere
  3. [x] Be specific about what level of conformance you expect for language tags: BCP 47 defines two levels of conformance, "valid" and "well-formed". more
    _Comments_gohere
  4. [x] Specifications may require implementations to check if language tags are "valid", but in most circumstances should only require that the language tags be "well-formed". more
    _Comments_gohere
  5. [ ] Specifications should require content and content authors to use "valid" language tags. more
    _Comments_gohere
  6. [ ] Specifications SHOULD refer to the IANA Language Subtag Registry instead of providing lists of codes extracted from ISO 639, ISO 3166, or other standards. more
    _Comments_gohere
  7. [x] Avoid creating a list of valid or supported language tags, language subtags, or locales. more
    _Comments_gohere

Declaring language

  1. [x] The specification should indicate how to define the default text-processing language for the resource as a whole. more
    _Comments_gohere
  2. [x] Content within the resource should inherit the language of the text-processing declared at the resource level, unless it is specifically overridden. more
    _Comments_gohere
  3. [x] Consider whether it is necessary to have separate declarations to indicate the text-processing language versus metadata about the expected use of the resource. more
    _Comments_gohere
  4. [x] If there is only one language declaration for a resource, and it has more than one language tag as a value, it must be possible to identify the default text-processing language for the resource. more
    _Comments_gohere
  5. [x] By default, blocks of content should inherit any text-processing language set for the resource as a whole. more
    _Comments_gohere
  6. [x] It should be possible to indicate a change in language for blocks of content where the language changes. more
    _Comments_gohere
  7. [ ] It should be possible to indicate language for spans of inline text where the language changes. more
     Since we return highly structured JSON and have a mechanism to set the language for each object, I don't think this applies to us

Identifying the language of strings (TBD)

Detecting & matching language

  1. [x] Reference BCP47 for language tag matching. more
    _Comments_gohere