Feature #8637: I18n documentation

• Status: Closed
• Assignee: zzak (zzak _)
• Target version: -

[zzak (zzak _)]

From the July 12 Developers Meeting:

Support for internationalized documentation was requested. RDoc needs a few
changes to support internationalized documentation, but there shouldn't be any
changes to Ruby itself required. There was some discussion of where the
internationalized docs would be stored.

https://bugs.ruby-lang.org/projects/ruby/wiki/DevelopersMeeting20130712#Internationalized-Documentation

===

The demo is available here: https://gist.github.com/zzak/5986014

Here's a quick todo list:

• RDoc API for i18n
• Add locale directory to source
• Look for translation maintainers
• Add translations

[kou (Kouhei Sutou)]

I will work on "RDoc API for i18n".

I will use the same approach what I did for YARD.

In the approach, gettext (*1) technology is used as the backend. It doesn't use i18n gem like approach like zzak's demo. Because i18n gem like approach can't detect the original documentation is changed after translated. Think about the following case:

(*1) http://en.wikipedia.org/wiki/Gettext

1. Add the original documentation in English.
2. Translate the original documentation into Japanese.
3. Update the original documentation in English. (But the key of the documentation isn't changed.)
4. (How to detect the original documentation is changed after it is translated into Japanese?)

If translators can't detect the original documentation is changed, they can't update the translated documentation.

Gettext technology uses the documentation itself as key and provides tools that can detect the original documentation is changed. So translators can update the translated documentation.

In the approach, RDoc generates .pot file from .rb/.c. .pot is "Portable Object Template" (*2) that has the original documentations. .pot is merged into #{LOCALE}.po such as ja.po. .po is "Portable Object" (*3) that has pairs of the original documentation and the translated documentation. Translators edit .po file. There are some .po editors. (I'm using po-mode.el in Emacs.)

(*2) http://www.gnu.org/software/gettext/manual/gettext.html#POT
(*3) http://www.gnu.org/software/gettext/manual/gettext.html#Files

There are some issues for this approach:

• RDoc needs .po format parser for translating the original documentation with .po. There are some implementations such as gettext gem and fast_gettext gem. I will choose a solution later. There are candidates. (1) Implementing translation feature as RDoc plugin. (2) Bundling .po parser.
• Updating .po generates many diff. It bothers confirming commit logs. I have an idea that solves this problem. But it is difficult that I describe it in English. :<

I will discuss about them after RDoc can generate .pot.

See also:

• The initial i18n related discussion on YARD Google Groups: https://groups.google.com/forum/#!topic/yardoc/Ca7LL-PGydU
• I18n related pull requests for YARD: https://github.com/lsegal/yard/pulls/kou?direction=desc&page=1&sort=created&state=closed
• The current core i18n related implementation for YARD: https://github.com/lsegal/yard/tree/master/lib/yard/i18n

[zzak (zzak _)]

@kou (Kouhei Sutou) Will the original English documentation stay the same? As embedded rdoc in cruby source?

[kou (Kouhei Sutou)]

zzak (Zachary Scott) wrote:

@kou (Kouhei Sutou) Will the original English documentation stay the same? As embedded rdoc in cruby source?

Yes. You don't need to change the current English documentation.

[zzak (zzak _)]

Sutou-san has began implementation for this on rdoc tracker: https://github.com/rdoc/rdoc/pull/254

[jeremyevans0 (Jeremy Evans)]

• Status changed from Open to Closed