Project

General

Profile

Actions

Feature #8637

closed

I18n documentation

Added by zzak (zzak _) over 10 years ago. Updated over 2 years ago.

Status:
Closed
Assignee:
Target version:
-
[ruby-core:56005]

Description

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

Updated by kou (Kouhei Sutou) over 10 years ago

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:

Updated by zzak (zzak _) over 10 years ago

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

Updated by kou (Kouhei Sutou) over 10 years ago

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.

Updated by zzak (zzak _) over 10 years ago

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

Actions #5

Updated by jeremyevans0 (Jeremy Evans) over 2 years ago

  • Status changed from Open to Closed
Actions

Also available in: Atom PDF

Like0
Like0Like0Like0Like0Like0