I18N Self-review

[iherman]

Short i18n review checklist is here. The relevant documents are:

• https://www.w3.org/TR/pub-manifest/
• https://www.w3.org/TR/audiobooks/

The second document is largely based on the first, and adds comparatively very little; these additions are all irrelevant in terms of internationalization.

Note, also, that the first document was originally developed under the name "Web Publication" in a separate repository, i.e., the earlier issues referred to are in the https://github.com/w3c/wpub repository.

Self test

(Only the relevant "sub" forms below have been copied from the i18n form. Other entries in that form are non-applicable.)

1. If the spec (or its implementation) contains any natural language text that will be read by a human (this includes error messages or other UI text, JSON strings, etc, etc),

   1. ​It should be possible to associate a language with any piece of natural language text that will be read by a user. more

   2. ​Where possible, there should be a way to label natural language changes in inline text. more

      N/A (Not Applicable)

   3. ​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

      See the global publication language tag

   4. ​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

      The language tag can be set both globally and on individual items

   5. ​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

      N/A (Not Applicable) (the mechanism is inherited from JSON-LD)

   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

      There is a separate (global and local) marker for the language used in the manifest, and another one for the language of the publication. The latter is a list with decreasing priority for possibly several languages.
      (At this moment, ie, 27.08.'19, this is not yet in the draft, but it will be; see the relevant WG resolution.)

   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

      N/A (Not Applicable) (there is no mechanism to set the language of "external" resources; it is up to the individual resources, e.g., HTML files, to do that).

   8. ​Values for language declarations must use BCP 47. more

   9. ​Refer to BCP 47, not to RFC 5646. more

   10. ​Be specific about what level of conformance you expect for language tags. The word "valid" has special meaning in BCP 47. Generally "well-formed" is a better choice.

   11. ​Reference BCP47 for language tag matching.

   12. ​The specification should indicate how to define the default text-processing language for the resource as a whole. more

       See the global publication language tag.

   13. ​Content within the resource should inherit the language of the text-processing declared at the resource level, unless it is specifically overridden.

   14. ​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

       N/A (Not Applicable) (only one language is provided)

   15. ​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

       N/A (Not Applicable) (there is only one declaration per resource).

   16. ​By default, blocks of content should inherit any text-processing language set for the resource as a whole. more

       N/A (Not Applicable) (there is no concept of a "block of content").

   17. ​It should be possible to indicate a change in language for blocks of content where the language changes. more

       N/A (Not Applicable) (there is no concept of a "block of content").

   18. ​It should be possible to indicate language for spans of inline text where the language changes. more

       N/A (Not Applicable) (JSON(-LD) operates with single texts only.)

   19. ​It must be possible to indicate base direction for each individual paragraph-level item of natural language text that will be read by someone. more

       N/A (Not Applicable) (there is no concept of a "paragraph level text").

   20. ​It must be possible to indicate base direction changes for embedded runs of inline bidirectional text for all natural language text that will be read by someone. more

       N/A (Not Applicable): (JSON(-LD) operates with single texts only.)

   21. ​Annotating right-to-left text must require the minimum amount of effort for people who work natively with right-to-left scripts. more

       See the definition of inDirection.

   22. ​Do not assume that direction can be determined from language information. more

   23. ​Values for the default base direction should include left-to-right, right-to-left, and auto. more

   24. ​Provide metadata constructs that can be used to indicate the base direction of any natural language string. more

       This can be done globally, but not locally. The issue has been discussed elsewhere (see, e.g., RDF Literals and Base Directions); essentially, this specification is based on JSON-LD and cannot unilaterally add new JSON-LD level structures to the manifest. This means that, in this version, this feature cannot be provided. See the discussion in #354, as well as the text in the specification explaining the situation.

   25. ​Specify that consumers of strings should use heuristics, preferably based on the Unicode Standard first-strong algorithm, to detect the base direction of a string except where metadata is provided. more

       See the discussion in the specification.

   26. ​Where possible, define a field to indicate the default direction for all strings in a given resource or document. more

   27. ​Do NOT assume that a creating a document-level default without the ability to change direction for any string is sufficient. more

   28. ​If metadata is not available due to legacy implementations and cannot otherwise be provided, specifications MAY allow a base direction to be interpolated from available language metadata. more

       N/A (Not Applicable)

   29. ​Specifications MUST NOT require the production or use of paired bidi controls. more

2. If the spec (or its implementation) allows content authors to produce typographically appealing text, either in its own right, or in association with graphics.

   N/A (Not Applicable)

3. If the spec (or its implementation) allows the user to point into text, creates text fragments, concatenates text, allows the user to select or step through text (using a cursor or other methods), etc.

   N/A (Not Applicable)

4. If the spec (or its implementation) allows searching or matching of text, including syntax and identifiers

   N/A (Not Applicable)
   　

5. If the spec (or its implementation) sorts text

   N/A (Not Applicable)

6. If the spec (or its implementation) captures user input

   N/A (Not Applicable)

7. If the spec (or its implementation) deals with time in any way that will be read by humans and/or crosses time zone boundaries

   The two items that use dates (datePublished and dateModified) are defined as ISO8601 data (which should cover all the points below).

   1. ​When defining calendar and date systems, be sure to allow for dates prior to the common era, or at least define handling of dates outside the most common range.
   2. ​When defining time or date data types, ensure that the time zone or relationship to UTC is always defined.
   3. ​Provide a health warning for conversion of time or date data types that are "floating" to/from incremental types, referring as necessary to the Time Zones WG Note. more
   4. ​Allow for leap seconds in date and time data types. more
   5. ​Use consistent terminology when discussing date and time values. Use 'floating' time for time zone independent values.
   6. ​Keep separate the definition of time zone from time zone offset.
   7. ​Use IANA time zone IDs to identify time zones. Do not use offsets or LTO as a proxy for time zone.
   8. ​Use a separate field to identify time zone.
   9. ​When defining rules for a "week", allow for culturally specific rules to be applied. more
   10. ​When defining rules for week number of year, allow for culturally specific rules to be applied.
   11. ​When non-Gregorian calendars are permitted, note that the "month" field can go to 13 (undecimber).
   12. If the spec (or its implementation) allows any character encoding other than UTF-8.

8. If the spec (or its implementation) defines markup.

   N/A (Not Applicable)

9. If the spec (or its implementation) deals with names, addresses, time & date formats, etc

   (Only names are relevant in the specification.)

   1. ​Check whether you really need to store or access given name and family name separately. more

      Only a single name field is used.

   2. ​Avoid placing limits on the length of names, or if you do, make allowance for long strings. more

   3. ​Try to avoid using the labels 'first name' and 'last name' in non-localized contexts. more

   4. ​Consider whether it would make sense to have one or more extra fields, in addition to the full name field, where users can provide part(s) of their name that you need to use for a specific purpose. more

      N/A (Not Applicable) (The class used for a Person has been defined by schema.org, this specification just takes it over. schema.org's Person has a number of relevant term, and this WG does not want to touch that class' definition.

   5. ​Allow for users to be asked separately how they would like you be addressed when someone contacts them. more

      N/A (Not Applicable) (there is no interaction with the user in the creation of this field).

   6. ​If parts of a person's name are captured separately, ensure that the separate items can capture all relevant information. more

      N/A (Not Applicable)

   7. ​Be careful about assumptions built into algorithms that pull out the parts of a name automatically. more

      N/A (Not Applicable)

   8. ​Don't assume that a single letter name is an initial. more

      N/A (Not Applicable)

   9. ​Don't require that people supply a family name. more

   10. ​Don't forget to allow people to use punctuation such as hyphens, apostrophes, etc. in names. more

   11. ​Don't require names to be entered all in upper case. more

   12. ​Allow the user to enter a name with spaces. more

   13. ​Don't assume that members of the same family will share the same family name. more

       N/A (Not Applicable)

   14. ​It may be better for a form to ask for 'Previous name' rather than 'Maiden name' or 'née'. more

       N/A (Not Applicable)

   15. ​You may want to store the name in both Latin and native scripts, in which case you probably need to ask the user to submit their name in both native script and Latin-only form, as separate items. more

       All "name" fields are defined as (possibly) arrays of names, and each item can have its language tag set.

10. If the spec (or its implementation) describes a format or data that is likely to need localization.

    N/A (Not Applicable)

11. If the spec (or its implementation) makes any reference to or relies on any cultural norms

    N/A (Not Applicable)

[iherman]

@aphillips,@r12a : comments?

[xfq]

The link to the Audiobook Profile seems broken?

[iherman]

Oops… sorry. I have changed the reference. Thanks!

[xfq]

Thanks @iherman! (I fixed some other broken links I noticed while reading the self review.)

[iherman]

@xfq, most of the other links come from the original review form, I have just copy/pasted it. Maybe it is worth checking with @r12a to see where those updates should go...

[xfq]

@iherman I just fixed some links to the pub-manifest spec (there were typos in the URL).

[iherman]

@xfq the eagle-eye:-)

[r12a]

Where possible, there should be a way to label natural language changes in inline text. more
N/A (Not Applicable)

I think that this is applicable (you may have a book title that is multilingual), but there is no way to achieve it other than using HTML markup, right?

[iherman]

Well... there is no such thing as inline text in the manifest, that is what misled me. But yes, it may be possible to imagine a multilingual book title, but that would indeed require HTML markup.

Although not exactly the same, but the book title's item is defined as a sequence of literals, i.e., it is possible to add several titles. The main reason of having this is to allow for titles in different languages to co-exist in the manifest. That can be done without any problems.

[aphillips]

I have reviewed the open issues from the I18N horizontal review of this spec and all of them appear to have been addressed to our satisfaction. Thank you for your support.

Issues: https://github.com/w3c/i18n-activity/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Awpub

[iherman]

Thanks @aphillips