Re: i18n/l10n summary

[Jean-Christophe Helary]

> On Jul 23, 2017, at 23:39, Eli Zaretskii <address@hidden> wrote:
> 
>> From: Jean-Christophe Helary <address@hidden>
>> Date: Sun, 23 Jul 2017 08:54:36 +0900
>> Cc: address@hidden
>> 
>>>> After checking the files I realized that all had "@include docstyle.texi" 
>>>> which already had "@documentencoding UTF-8", so I just added 
>>>> "@documentlanguage en_US" there.
>>> 
>>> en_US is the default in the absence of an explicit @documentlanguage,
>>> so I'm not sure I understand why would we need to add it.  It will
>>> change nothing, AFAIK.
>> 
>> When po4a extracts translatable text to create the pot files docstyle.texi 
>> will also have a pot file that includes "@documentlanguage en_US" and that 
>> will allow translators to change that to "@documentlanguage fr_FR" etc. If 
>> we don't had that to docstyle.texi somebody will have to add the language 
>> string manually and that's an extra task that we'll have to check.
> 
> Sorry, I don't think I follow.  Does po4a understand Texinfo in
> general and the @documentlanguage directive in particular?

No, it doesn't. It just extracts text. po4a is the tool that has been developed 
to allow people who are familiar with po to work with documentation files. It 
just round-trips the document to and from the po format and is not at all as 
smart as gettext.

For ex. The current docstyle.texi is converted to a docstyle.texi.fr.po whose 
contents is:

================================
# SOME DESCRIPTIVE TITLE
# Copyright (C) YEAR Free Software Foundation, Inc.
# This file is distributed under the same license as the PACKAGE package.
# FIRST AUTHOR <address@hidden>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"POT-Creation-Date: 2017-07-24 08:11+0900\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <address@hidden>\n"
"Language-Team: LANGUAGE <address@hidden>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=CHARSET\n"
"Content-Transfer-Encoding: 8bit\n"

#. type: Plain text
#: docstyle.texi:6
msgid "@documentencoding UTF-8 @documentlanguage en_US"
msgstr ""
================================

It is arguable that we could have something better like:

#. type: documentencoding
#: docstyle.texi:2
msgid "UTF-8"
msgstr ""

#. type: documentlanguage
#: docstyle.texi:3
msgid "en_US"
msgstr ""

but that's a separate discussion.

> And if it doesn't understand Texinfo, why would
> the presence of @documentlanguage change anything in its output?

po4a presents the strings to the translator for modification. As far as the 
translator is concerned, that is the only place where the language for the 
whole documentation set is presented and that the one and only place that needs 
to be changed so that the whole documentation gets the appropriate 
@documentlanguage directive.

> And where would someone need to add the language string manually -- in
> what file?

If the directive were not present, somebody would need to manually add 
@documentlanguage [appropriate language] directive to the docstyle.texi file of 
that language.

Jean-Christophe