Closed Bug 1306011 Opened 3 years ago Closed 3 years ago

Prepare the docs to land in mozilla-central

Categories

(L20n :: General, defect)

defect
Not set

Tracking

(Not tracked)

RESOLVED FIXED

People

(Reporter: stas, Assigned: stas)

References

Details

(Whiteboard: [gecko-l20n])

Attachments

(2 files)

Let's clean up the current docs in larch which are mostly about compare-locales and create a new index.rst for the Localization chapter which includes TOC links to compare-locales, glossary, how to use l20n in firefox front-end and the syntax guide.

It will be helpful to build the docs locally to make sure everything looks right:

    https://gecko.readthedocs.io/en/latest/#managing-documentation
Blocks: 1291693
Comment on attachment 8807880 [details]
Bug 1306011 - Document L20n.

https://reviewboard.mozilla.org/r/90862/#review90818

There are a few bugs down there, some old, some new.

Generally speaking, I think that's the setup of files here is good.

I'm OK with some of the more heavyweight edits to be done in follow-up bugs on larch, though.

I'd like to give this one more turn around.

PS: Locally, I've been diffing against the docs we have in l20n.js, it might be useful for our own history on larch to make that explicit? Not necessary, though, if I'm the only one looking at it.

::: l10n/docs/index.rst:40
(Diff revision 1)
> +repositories are on https://hg.mozilla.org/l10n-central/.
> +
> +You can search inside our localized files on `Transvision`_ and
> +http://dxr.mozilla.org/l10n-mozilla-aurora/.
> +
> +.. _Transvision: https://github.com/l20n/l20n.js/blob/master/docs/syntax.rst

wrong link

::: l10n/docs/l20n.rst:71
(Diff revision 1)
> +You can group resources under a name with the ``name`` attribute::
> +
> +    <link rel="localization" name="main" href="/browser/about-dialogftl">
> +    <link rel="localization" name="new-tab" href="/browser/new-tab.ftl">
> +
> +If the ``name`` attribute is not defined, ``main`` is assumed.

I think we still need the bundle docs here, and explain what to do in XUL. Also bug 1306595 comment 0.

Should I open new bugs on that?

::: l10n/docs/l20n.rst:177
(Diff revision 1)
> +elements but only modifies their text nodes and their attributes. This makes 
> +it possible to use L20n in conjunction with MVC frameworks.
> +
> +You can learn more about DOM Overlays in the `design document`_.
> +
> +.. _design document: https://github.com/stasm/spec/blob/master/dom-overlays.markdown

I think we should put this somewhere that's not in your user account. Either on the l20n/spec repo, or import that document into gecko.rtd, too.

::: l10n/docs/legacy.rst:8
(Diff revision 1)
> -============
> +=====================
> +
> +This document describes the legacy localization infrastructure used in Gecko
> +before 2016.  Unless it has been ported to L20n, existing code still uses this
> +legacy architecture.  New code should should use the new L20n infrastructure
> +and the FTL file format.  Refer to :doc:`l20n` for more information.

I'd not reference 2016 here in the docs, just go for "prior to L20n".

Some of the content here will need to be merged back into l20n.rst. File locations, l10n.ini. Possibly l10n-merge, too.

Not sure if that's a follow-up bug, though.
Attachment #8807880 - Flags: review?(l10n) → review-
Comment on attachment 8807880 [details]
Bug 1306011 - Document L20n.

https://reviewboard.mozilla.org/r/90862/#review90818

Thanks for the review, Pike!

I'll land the small changes I made to the docs in the l20n.js repo, so they will be visible in the history there.  I don't think we need to replay them on larch.

> wrong link

Gah, a copy&paste gone wrong. Thanks.

> I think we still need the bundle docs here, and explain what to do in XUL. Also bug 1306595 comment 0.
> 
> Should I open new bugs on that?

Can you explain what you mean by "the bundle docs"?

> I think we should put this somewhere that's not in your user account. Either on the l20n/spec repo, or import that document into gecko.rtd, too.

I suggested moving this to l20n/spec a week ago in an email thread about the L20n docs, so I'll be happy to do it now.

> I'd not reference 2016 here in the docs, just go for "prior to L20n".
> 
> Some of the content here will need to be merged back into l20n.rst. File locations, l10n.ini. Possibly l10n-merge, too.
> 
> Not sure if that's a follow-up bug, though.

I think I'd prefer to ask you to make these edits as you know the legacy system the best.  For this reason, it might be easier to do it in a new bug, or as a new patch here.
(In reply to Staś Małolepszy :stas from comment #3)
> Comment on attachment 8807880 [details]
> Bug 1306011 - Document L20n.
> 
> https://reviewboard.mozilla.org/r/90862/#review90818
> 
> Thanks for the review, Pike!
> 
> I'll land the small changes I made to the docs in the l20n.js repo, so they
> will be visible in the history there.  I don't think we need to replay them
> on larch.
> 
> > wrong link
> 
> Gah, a copy&paste gone wrong. Thanks.
> 
> > I think we still need the bundle docs here, and explain what to do in XUL. Also bug 1306595 comment 0.
> > 
> > Should I open new bugs on that?
> 
> Can you explain what you mean by "the bundle docs"?

from https://github.com/l20n/l20n.js/blob/master/docs/gecko.rst:

> You can group resources under a name with the name attribute:
> 
> <link rel="localization" name="main" href="/browser/about-dialogftl">
> <link rel="localization" name="new-tab" href="/browser/new-tab.ftl">
>
> If the name attribute is not defined, main is assumed.

That's kinda "why would I want to do that?"

> > I think we should put this somewhere that's not in your user account. Either on the l20n/spec repo, or import that document into gecko.rtd, too.
> 
> I suggested moving this to l20n/spec a week ago in an email thread about the
> L20n docs, so I'll be happy to do it now.
> 
> > I'd not reference 2016 here in the docs, just go for "prior to L20n".
> > 
> > Some of the content here will need to be merged back into l20n.rst. File locations, l10n.ini. Possibly l10n-merge, too.
> > 
> > Not sure if that's a follow-up bug, though.
> 
> I think I'd prefer to ask you to make these edits as you know the legacy
> system the best.  For this reason, it might be easier to do it in a new bug,
> or as a new patch here.

Let's put that into a new bug.
Assignee: nobody → stas
Status: NEW → ASSIGNED
Comment on attachment 8807880 [details]
Bug 1306011 - Document L20n.

https://reviewboard.mozilla.org/r/90862/#review91542

r=me, thanks.
Attachment #8807880 - Flags: review?(l10n) → review+
Status: ASSIGNED → RESOLVED
Closed: 3 years ago
Resolution: --- → FIXED
You need to log in before you can comment on or make changes to this bug.