Re: [widgets] P&C LC comments on I18N/L10N

Hi Jere,

Fixes and some questions below. I got stuck on your last point, can
you please clarify it or suggest more clearly what you want me to do
there?

On Wed, Jun 3, 2009 at 11:47 AM,  <Jere.Kapyaho@nokia.com> wrote:
> Marcos, all,
>
> here's a bunch of comments related to the I18N/L10N related parts of the
> Widgets 1.0: Packaging and Configuration spec (Last Call i.e. Working Draft
> 28 May 2009).

Great!

> /1/ Order of material
>
> >From an editorial standpoint, I think that the "7.2 Examples" subsection
> should really be the last one in this section.

Right. Moved it.

> Information about element-based localization, which now is 8.15, should
> appear in section 7, because the concepts are used in Section 8 before they
> are even defined. It would be good to have all related info in the same
> section.
>
> My suggestion for the organization of the material is:
>
> 7 Internationalization and localization
>    7.1 Localization guidelines
>    7.2 Folder-based localization (used to be 7.3)
>    7.3 Element-based localization (used to be 8.15)
>    7.4 Localization examples (used to be "7.2 Examples", note new name)

Right. I've moved everything and renamed examples > "Localization examples".

> This would make the material flow better and have all the concepts defined
> before they are used.

I will need you to check this before we republish. Is that OK?

> Also, the whole of Section 7 should actually appear right before the
> processing steps (i.e., after the current Section 8).

I moved everything as you suggested.

> /2/ Content of examples
>
> The localization examples are non-normative, but many developers are going
> to study them closely, so it pays to fine-tune them a little (and fix a few
> bugs).

Very true. WRT fine tuning, I'm open to suggestions. Wrt bug fixes...

> In the simple example, the second file "/sp/index.html" should be labeled
> "/locales/es/index.html". Similarly, in the complex example, "/locales/sp/"
> should be "/locales/es".

Fixed.

> The complex example refers to several files which really have the same
> purpose. I think they should also have the same name, otherwise they cannot
> be found by the same reference. That is, "/locales/es/gatos.html" should be
> called "/locales/es/cats.html". Or is it intentional?

Never is:) That is a left over mistake from when we had multiple configs.

> In "Fallback Behaviour Example", first paragraph, last sentence should read:
> "The purpose of this 'fallback' model is to reduce the number of files that
> need to be created in order to achieve localization of a widget package."
> (remove 'n' from 'then', add 'in order')

fixed (used your text).

>
> /3/ Folder-based localization
>
> Suggested addition to the authoring guideline: "A Conformance Checker (CC)
> SHOULD issue a warning if there are empty locale folders in the widget
> package."
>

Added.

> This statement in the authoring guideline is puzzling: '[That is,] authors
> cannot simply put shared files into a language level folder, but need to put
> all files needed into the language level folder for the widget to work (for
> example, having "a.gif" in both "/locales/zh-Hans/" folder and
> "locales/zh").' Isn't this the opposite of what is supposed to happen in the
> fallback model? If the same "a.gif" is good for both zh-Hans and zh, it
> should be possible for the author to include it just once in "/locales/zh".

Yes, this is correct.

> If the user's language list includes 'zh-Hans', it will also include 'zh',
> as per Step 5. So "a.gif" will be found eventually.
>

Right.

> Replace '"shared1.gif, shared2.gif"' with '"shared1.gif" and "shared2.gif"'.

Fixed.

> Priority is probably a bad term to use with regard to localized folders.

I changed it to:
[[
In the example below, assuming the widget's locale is "zh-hans-cn":
* The a.gif file in the "zh-Hans-CN" locale folder would be used
instead of the a.gif file in the zh-Hans locale folder.
* The b.gif file in the zh-Hans locale folder would be used instead of
the b.gif file in the zh locale folder.
* The c.gif in the zh locale folder would be used instead of the c.gif
file root of the widget package.
* The d.gif file would always be used from the root of the widget, as
it is not associated with any locales and is hence available to all
locales.
]]

> /4/ The xml:lang attribute
>
> Does the XML specification state that the values of xml:lang attributes must
> be unique across instances of the same element?

No.

> If yes, it is probably
> redundant to repeat that in the context of all the elements in the
> configuration document. If not, the statement about uniqueness could still
> be factored out, for example to section 8.4, to avoid repetition.

Although redundant, I think I will leave this as is. If it's still
annoying, we can remove it in CR as it would be an editorial change
and it would have no normative impact. Is that OK?

> /5/ Processing steps
>
> Step 3: the concept of "localized config doc" appears in the Configuration
> Defaults table, but that doesn't seem to exist anymore. (See also Step 6.)
>

Fixed.

> Step 5: replace "unprocessed locales lists" with "unprocessed locales list"
> throughout.

fixed

>
> Consider replacing "user agent's locales" with "user agent locales"
> throughout the spec.

Fixed.

> In the first example of Step 5, why would en and en-au be swapped around
> when decomposed?

I was missing an en, which might have been causing confusion. Taking
the first part of the example:
"en-us,en-au,fr,en"

Would become:
"en-us,en-au,fr,en"

And would normalize to:
"en-us,en,en-au"

_however_, during the F2F, we changed the "normalization" behavior so
that the result would now be: "en-us,en-au,en" (i.e., repetitions are
removed from left to right, not from right to left).

> Would 'canonicalization' be a more suitable term here than
> 'decomposition'?

I think both of those terms are scary, so I've just said "would
become" instead of "would decompose".

> /6/ Runtime resolution of localized resources
>
> What specification should describe how a reference to a resource (which
> could be in a localized folder) is resolved at runtime, based on the user's
> language range?

Sorry, I don't understand this question. Can you please rephrase it?

> That is not quite in the domain of the packaging
> specification, given that it is runtime behavior. This functionality is
> sketched in the fallback behavior example, but it is non-normative.

As above.

> Thanks for considering these comments.

Thanks for the detailed review.

-- 
Marcos Caceres
http://datadriven.com.au

Received on Monday, 29 June 2009 10:31:29 UTC