747482 - Add some documentation for the l10n module.

Status: RESOLVED FIXED

(Add-on SDK Graveyard :: Documentation, defect, P1)

Description

[Wes Kocher (:KWierso) (Not reading bugmail; email directly if needed)]

l10n should have some documentation show up in the docs sidebar, even if it just points to the localization tutorial at https://addons.mozilla.org/en-US/developers/docs/sdk/latest/dev-guide/tutorials/l10n.html

Comment 1

[Will Bamberg [:wbamberg]]

Attachment: added packages/addon-kit/docs/l10n.md

Comment 2

[Alexandre Poirot [:ochameau]]

Comment on attachment 623284 [details] [diff] [review]
added packages/addon-kit/docs/l10n.md

Review of attachment 623284 [details] [diff] [review]:
-----------------------------------------------------------------

Looks good, just need to adapt phrasing in order to explain that we can *either* pass `count` or `placeholder(s)`.
(Actually, `count` can be seen as a special placeholder where we use `%d` instead of `%s`)

::: packages/addon-kit/docs/l10n.md
@@ +87,5 @@
> +  Optional parameters.
> +  After the identifier parameter and count parameter (if the count parameter
> +  is present) you can supply one or more placeholder strings, that are to be
> +  inserted into the translated string at locations defined by
> +  the translator.

Actually, you can either pass an integer if the key maps to a plural form (key[one]=One key[other]=Many)
or multiple strings for placeholders but you can't pass both at the same time, like:
  key[one]=One %s
  key[other]=%d %s's
  _("key", 1, "foo");
  // It won't work. %s won't be replaced.

But that's something I can implement. Do you think I should? (Would it be easier to explain/understand/use?)
My main reason for doing only simple things is to be able to fit to Gaia and l20n behavior.

Comment 3

[Will Bamberg [:wbamberg]]

(In reply to Alexandre Poirot (:ochameau) from comment #2)
> Comment on attachment 623284 [details] [diff] [review]
> added packages/addon-kit/docs/l10n.md
> 
> Actually, you can either pass an integer if the key maps to a plural form
> (key[one]=One key[other]=Many)
> or multiple strings for placeholders but you can't pass both at the same
> time, like:
>   key[one]=One %s
>   key[other]=%d %s's
>   _("key", 1, "foo");
>   // It won't work. %s won't be replaced.

Oh, I had misread the code, but now I see it. 

> But that's something I can implement. Do you think I should? (Would it be
> easier to explain/understand/use?)

To me plurality and placeholders seem to be orthogonal, so that's probably why I assumed you could have both. Having both seems like a valid use case, but I'm not a localization expert.

> My main reason for doing only simple things is to be able to fit to Gaia and
> l20n behavior.

Fitting with Gaia and l20 sounds like a good idea. Then maybe it's best to keep it like this, document it, and add support for both if people ask for it?

Comment 4

[Alexandre Poirot [:ochameau]]

(In reply to Will Bamberg [:wbamberg] from comment #3)
> > My main reason for doing only simple things is to be able to fit to Gaia and
> > l20n behavior.
> 
> Fitting with Gaia and l20 sounds like a good idea. Then maybe it's best to
> keep it like this, document it, and add support for both if people ask for
> it?

Sounds like a good plan, as l20n is going to support both.

Comment 5

[[github robot]]

Commit pushed to master at https://github.com/mozilla/addon-sdk

https://github.com/mozilla/addon-sdk/commit/d3795bdfb4dfe07b714978bb2182b92315b02c49
Bug 747482 - Add some documentation for the l10n module.;r=@ochameau

Comment 6

[[github robot]]

Commit pushed to stabilization at https://github.com/mozilla/addon-sdk

https://github.com/mozilla/addon-sdk/commit/843e6dd09f9014ebf4e9fe4d93cb46b3a513739f
Bug 747482 - Add some documentation for the l10n module.;r=@ochameau
(cherry picked from commit d3795bdfb4dfe07b714978bb2182b92315b02c49)