Closed Bug 1202658 Opened 9 years ago Closed 8 years ago

Please unify best practice docs for Localizing Firefox OS Apps - App Center | MDN

Categories

(Developer Documentation Graveyard :: Localization, defect)

Product:
Developer Documentation Graveyard
Component:
Localization
Type:
defect
Priority:
Not set
Severity:
normal

Tracking

(Not tracked)

Status:
RESOLVED WONTFIX

People

(Reporter: anaran, Unassigned)

References

(
URL
)

Details

See these links:

https://developer.mozilla.org/en-US/Apps/Build/Localization/Localizing_Firefox_OS_Apps#Localizing_HTML_from_JavaScript_Best_practice
https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Developing_Gaia/localization_code_best_practices

  referenced from

https://developer.mozilla.org/en-US/Apps/Build/Localization/Localizing_Firefox_OS_Apps#The_get_Method_(deprecated)

Details:

The get Method (deprecated)

Note: Please use best practices, also documented at Gaia localization code best practices instead.

Problem:

I put in this new Note today.

It shows best practices documented in two places.

This is obviously a maintenance issue. How should these sources be consolidated?

http://mzl.la/1vxCDgA
Hi there! My preference would be to get rid of 

https://developer.mozilla.org/en-US/Apps/Build/Localization/Localizing_Firefox_OS_Apps

and then linking to 

https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Developing_Gaia/localization_code_best_practices

instead, adding in anything that is missing. I think the latter is more comprehensive; it was also written later, so is probably more up to date. Does this work for you?
The problem is that the latter is intended for people localizing the Gaia UX for distribution on phones, whereas the "Localizing Firefox OS Apps" article is targeted at everyday app developers. I assume there are differences in their tasks. If not, then these could be merged.
This is the thing - they are kind of aimed at different audience segments, so there are difference, even thought they are very similar.

I thought I could perhaps try to unify them. Although saying that, could we not just to one instance of the best practices, instead of two, in the aforementioned note?
:sheppy also mentioned this in irc:

> Or create a third page which is overall best practices, then reference it from each page, which then has less overlap... (reference or even transclude)

> See https://developer.mozilla.org/en-US/docs/Template:page

Seems a little sophisticated, but perhaps it's the right way to handle related topic material.

If techniques converge then the leaf pages basically become empty.

I am writing a firefox os app which so far runs fine there as well as
* packages desktop web app (windows and linux) installable from hosted install.html
* hosted app served out of my git working directory by "python -m SimpleHTTPServer"

I mention this because the more those localization practices can stay the same, the better.

Perhaps a way to start if to slim down https://developer.mozilla.org/en-US/Apps/Build/Localization/Localizing_Firefox_OS_Apps to its absolutely necessary specifics.

E.g. does it still have to use a local copy as documented in https://developer.mozilla.org/en-US/Apps/Build/Localization/Localizing_Firefox_OS_Apps#L10n_Script_reference

BTW,
https://developer.mozilla.org/en-US/Apps/Build/Localization/Localizing_Firefox_OS_Apps#The_localeFormat_method
mentions use of navigator.mozL10n.ready in an example, for which https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Developing_Gaia/localization_code_best_practices#mozL10n.ready_will_cause_memory_leaks has a relevant recommendation making the former example a bad practice IIUC.
Ok, I've looked through all our app localization articles in detail, and have come up with a plan. I'm also needinfo'ing Zibi, our FxOS localization champion, to check that he thinks the plan is ok.

The content we have is:

1. https://developer.mozilla.org/en-US/Firefox_OS/Developing_Gaia/localization_code_best_practices
high level best practices, assumes you know that basics already

2. https://developer.mozilla.org/en-US/Apps/Build/Localization/Getting_started_with_app_localization
complete beginner's guide - goes through the localisation process, from start to finish, at a basic level

3. https://developer.mozilla.org/en-US/Apps/Build/Localization/Setup
https://developer.mozilla.org/en-US/Apps/Build/Localization/Localizing_strings_in_HTML
https://developer.mozilla.org/en-US/Apps/Build/Localization/Localizing_strings_in_JavaScript
https://developer.mozilla.org/en-US/Apps/Build/Localization/Localizing_the_manifest
https://developer.mozilla.org/en-US/Apps/Build/Localization/Developing_Bidi_Apps
Provides deeper dives into each aspect of localisation, generally quite referencey

4. https://developer.mozilla.org/en-US/Apps/Build/Localization/App_Localization_with_Transifex
Information on using the transifex service to localize apps

5. https://developer.mozilla.org/en-US/Apps/Build/Localization/Localizing_Firefox_OS_Apps
Complete guide to localizing apps, with a lot of detail than 1. 

6. https://developer.mozilla.org/en-US/Apps/Build/Localization/Localizing_Firefox_OS_Boilerplate_App
Also provides a guide to localizing apps, more by way of a case study, also has a bunch of Transifex info.

My proposal is as follows:

* Move 1 out of the Firefox_OS/Developing_Gaia/ docs tree, and into the same tree as all the other documents (e.g. Apps/Build/), then link to there from the Developing_Gaia article - this will make things less confusing as we will have one location, not two. I honestly don't think the different resources are catering to different audiences, so this will be fine.

* Get rid of 6 completely, but perhaps include the transifex stuff in 4, if transifex is still relevant.

* Dissolve 5 and move the relevant content into 2 and 3, where appropriate. 5 is a nice article, but I think it tries to do too many things at once and is overlong. Splitting it up into a beginner guide plus reference content would be more effective for beginners and advanced users, imo (see the next two bullets)

* Flesh 2 out to make it a slightly more detailed guide, and link to 3 for more detail where appropriate. 2 should remain nice and accessible to beginners.

* Turn the articles in 3 into proper reference pieces that provide complete coverage of all L10n.js has to offer. Add in anything we are missing (with help from Zibi, Stas, etc.)

So we will end up with

* Beginner's guide
* Advanced best practices for more experienced l10n devs
* Multiple reference article providing complete coverage
* (A couple more random bits at the end, secondary the the main three resources)

What do we think?
Flags: needinfo?(gandalf)
I believe we want to remove transifex related stuff. CC'ing Pike to confirm.

I like to overall approach. We will have to update it as we're moving apps to use l20n.js instead of l10n.js, but we need another couple weeks to stabilize the API first.

So feel free to start consolidating articles and I'll be happy to review/update them to the final API's that we are going to use for Gaia/WebApps.
Flags: needinfo?(gandalf) → needinfo?(l10n)
(In reply to Eric Shepherd [:sheppy] from comment #2)
> The problem is that the latter is intended for people localizing the Gaia UX
> for distribution on phones, whereas the "Localizing Firefox OS Apps" article
> is targeted at everyday app developers. I assume there are differences in
> their tasks. If not, then these could be merged.

Once we move from l10n.js to l20n.js I believe we will be able to suggest one solution for both, but I agree that the discrepancy came from the fact that historically we were not able to (l10n.js was only for gaia).
(In reply to Zibi Braniecki [:gandalf][:zibi] from comment #6)
> I believe we want to remove transifex related stuff. CC'ing Pike to confirm.
> 
> I like to overall approach. We will have to update it as we're moving apps
> to use l20n.js instead of l10n.js, but we need another couple weeks to
> stabilize the API first.
> 
> So feel free to start consolidating articles and I'll be happy to
> review/update them to the final API's that we are going to use for
> Gaia/WebApps.

Cool - I will get started tomorrow, provided there are no major dissenters.

I think it will still be worth having L10n.js docs around for a while, as older versions of FxOS will still exist, and need l10n work done, right?

(In reply to Zibi Braniecki [:gandalf][:zibi] from comment #7)
> (In reply to Eric Shepherd [:sheppy] from comment #2)
> > The problem is that the latter is intended for people localizing the Gaia UX
> > for distribution on phones, whereas the "Localizing Firefox OS Apps" article
> > is targeted at everyday app developers. I assume there are differences in
> > their tasks. If not, then these could be merged.
> 
> Once we move from l10n.js to l20n.js I believe we will be able to suggest
> one solution for both, but I agree that the discrepancy came from the fact
> that historically we were not able to (l10n.js was only for gaia).

But 3rd party apps can currently use l10n.js now, right? Just clarifying ;-)
Yes. I would expect that we need around one more month to stabilize l20n.js to the point where we will feel confident to recommend it to everyone (both, Gaia devs and WebApp devs).

And yes, older versions (like 2.2 and 2.1) will rely on l10n.js. But if they target 2.5 third-party devs will be able to start using l20n.js once we freeze.
I also found this:

https://developer.mozilla.org/en-US/Firefox_OS/Developing_Gaia/Localizing_Firefox_OS

I'm guessing this is out of date and should be nuked?
Ok, I've done quite a lot of chopping down of the existing material:

https://developer.mozilla.org/en-US/Apps/Build/Localization

Most of the articles there were too wordy, and repeated the stuff in the main app localization article. Speaking of that article, I've taken most of that material and put it into here:

https://developer.mozilla.org/en-US/Apps/Build/Localization/Getting_started_with_app_localization

I've also put a bunch of stuff from the other articles into here:

https://developer.mozilla.org/en-US/Apps/Build/Localization/Localization_code_best_practices

So now the articles are not repetitious, and more pure in terms of style. The L10n.js reference (https://developer.mozilla.org/en-US/Apps/Build/Localization/L10n.js_reference) is now pure reference, and doesn't contain a bunch of other stuff. It would be nice for Zibi and Adrian to have a quick look through and let me know if anything seems missing or incorrect.

Things still to do:

1. Are we getting rid of the transifex stuff? I guess we just need to wait for Pike's answer to this.

2. We need to have a look at the reference article and fill in the members that are missing.

3. I also noticed that we have a proper set of API-style reference pages in the works for l10n: 

https://developer.mozilla.org/en-US/docs/Web/API/L10n

I am kinda loathe to spend time completing these when L20n is right around the corner, so I propose that for now we just fill the missing items in on the L10n.js reference article, and We'll do a proper set fo reference pages for L20n.
(In reply to Chris Mills (Mozilla, MDN editor) [:cmills] from comment #11)
> Ok, I've done quite a lot of chopping down of the existing material:
> 
> https://developer.mozilla.org/en-US/Apps/Build/Localization
> 
> Most of the articles there were too wordy, and repeated the stuff in the
> main app localization article. Speaking of that article, I've taken most of
> that material and put it into here:
> 
> https://developer.mozilla.org/en-US/Apps/Build/Localization/
> Getting_started_with_app_localization
> 
> I've also put a bunch of stuff from the other articles into here:
> 
> https://developer.mozilla.org/en-US/Apps/Build/Localization/
> Localization_code_best_practices
> 
> So now the articles are not repetitious, and more pure in terms of style.
> The L10n.js reference
> (https://developer.mozilla.org/en-US/Apps/Build/Localization/L10n.
> js_reference) is now pure reference, and doesn't contain a bunch of other
> stuff. It would be nice for Zibi and Adrian to have a quick look through and
> let me know if anything seems missing or incorrect.

Hi Chris, oh that was a lot of work you did!

I am not sure what specifically I should look at. I noticed quite some redirects but have not found any broken links so far. At this point I cannot comprehend all the changes, but will keep looking for obvious problems.

One thing I noticed, that is not new:

https://developer.mozilla.org/en-US/Firefox_OS/Developing_Gaia/Localizing_Firefox_OS#Setting_up_a_local_repo

referenced from

https://developer.mozilla.org/en-US/Apps/Build/Localization/Getting_started_with_app_localization#See_also

refers to https://hg.mozilla.org/gaia-l10n which I check exists and has recent updates.

Are these sources also available via git somewhere?
(In reply to Adrian Aichner [:anaran] from comment #12)
 
> Hi Chris, oh that was a lot of work you did!
> 
> I am not sure what specifically I should look at. I noticed quite some
> redirects but have not found any broken links so far. At this point I cannot
> comprehend all the changes, but will keep looking for obvious problems.

Checking for broken links is a really useful thing to; It would also be useful for you to start from the main landing page (https://developer.mozilla.org/en-US/Apps/Build/Localization), have a look around, and let me know if what you see makes sense and provides you all the information you need. There is definitely scope to fill gaps

> 
> One thing I noticed, that is not new:
> 
> https://developer.mozilla.org/en-US/Firefox_OS/Developing_Gaia/
> Localizing_Firefox_OS#Setting_up_a_local_repo
> 
> referenced from
> 
> https://developer.mozilla.org/en-US/Apps/Build/Localization/
> Getting_started_with_app_localization#See_also
> 
> refers to https://hg.mozilla.org/gaia-l10n which I check exists and has
> recent updates.
> 
> Are these sources also available via git somewhere?

That is a good question; I don't know if our localization repos are available in other ways.
(Doh, I had half of this written already)

Doing this iteratively now.

Let's remove the transifex pieces, they're no longer supported by our devrel folks.

I need to actually read https://developer.mozilla.org/en-US/Apps/Build/Localization/Getting_started_with_app_localization, but I also think that gandalf/stas should review that for technical correctness regarding l10n.js status and l20n.js status.

https://developer.mozilla.org/en-US/Apps/Build/Localization/L10n.js_reference looks like it's not a good reference anymore. Also gandalf/stas.

https://developer.mozilla.org/en-US/Apps/Build/Localization/Internationalization_helpers_IntlHelper_and_mozIntl is for gandalf to review.

The bidi work looks good, but there's more in Ahmed's posts, https://hacks.mozilla.org/author/nefzaoui/

TranslationTester can also be removed, that's not maintained anymore.
Flags: needinfo?(gandalf)
With apps going away, I guess we can just wontfix this?
Status: NEW → RESOLVED
Closed: 8 years ago
Flags: needinfo?(l10n)
Flags: needinfo?(gandalf)
Resolution: --- → WONTFIX
You need to log in before you can comment on or make changes to this bug.