Re: [gentoo-dev] News item: LINGUAS USE_EXPAND renamed to L10N

[Michał Górny]

On Mon, 06 Jun 2016 03:22:34 +0300
Mart Raudsepp <leio@g.o> wrote:

> First draft of news item for proceeding with LINGUAS USE_EXPAND rename
> to L10N independently of the INSTALL_MASK feature additions.
>
> I hope English natives will improve the sentence flow and grammar here
> :)
> Perhaps there's also a better title than with the technical USE_EXPAND
> mention.
>
>
> Title: LINGUAS USE_EXPAND renamed to L10N
> Author: Mart Raudsepp <leio@g.o>
> Content-Type: text/plain
> Posted: 2016-06-06
> Revision: 1
> News-Item-Format: 1.0
>
> The LINGUAS USE_EXPAND has been renamed to L10N, to avoid a conceptual
> clash with the standard gettext LINGUAS behaviour.
> L10N controls which extra localization support will be installed.
> This is usually used in case of extra downloads of language packs.
>
> If you have set LINGUAS in your make.conf, you should either copy or
> rename it to L10N, depending on if you want to filter the supported
> languages at build time or not via the gettext LINGUAS environment
> variable behaviour as described below. Note that this filtering does not
> affect only installed gettext catalog files (*.mo), but also lines of
> translations in an always shipped file (e.g *.desktop).
>
> LINGUAS maintains the standard gettext behaviour and will now work as
> expected with all package managers. It controls which language
> translations are built and installed. An unset value means all
> available, an empty value means none, and a value can be an unordered
> list of gettext language codes, with or without country codes.
> Usually only two letter language codes suffice, but can be limited with
> country codes with a 'll_CC' formatting, where 'll' is the language code
> and 'CC' is the country code, e.g en_GB. Some rare languages also have
> three letter language codes.
> If you want English with a set LINGUAS, it is suggested to list it with
> the desired country code, in case the default is not the usual en_US.
> It is also common to list "en" then, in case a package is natively
> written in a different language, but does provide an English translation
> for whichever country.
> A list of LINGUAS language codes is available at
> http://www.gnu.org/software/gettext/manual/gettext.html#Language-Codes
>
> Note that LINGUAS affects build time, and thus filters what ends up
> in binary packages. If you are building generic binary packages that
> should support all available language, you should not set LINGUAS.
>
> If you have per-package customizations of LINGUAS USE_EXPAND, you
> should also rename those from LINGUAS to L10N. This typically means
> renaming linguas_* to l10n_*.
>
> https://wiki.gentoo.org/wiki/Localization/Guide has also been updated
> to reflect this change.

So here's how I would word it. I think if we combine a few different
texts, we may end up with something good ;-).

---
The LINGUAS USE flag group has been renamed to L10N, in order to avoid
a conceptual clash between the Gentoo use of the name, and a standard
environment variable used by multiple gettext-based packages. Therefore,
from now on filtering localizations is supported on three independent
levels: L10N, LINGUAS and INSTALL_MASK.

The L10N flags affect built and installed localizations of the packages
listing those flags explicitly. They are fully controlled by
the package manager, and their values are defined globally. They do not
affect the packages not listing them explicitly.

The LINGUAS variable is now verbosely passed through to the build
system. It controls the localizations built and installed by packages
that use it, and that do not override it using L10N flags. Note that
due to the design, the localization stripping is done implicitly
and the package manager can not determine which localizations were
actually provided.

Additionally, the INSTALL_MASK improvements available in Portage 2.3.0
make it possible to filter localizations at package merge stage. In this
case, the filtering is done on installed directories transparently,
and the build process and binary packages are not affected.

If you were using LINGUAS before, you most likely want to replace it
with L10N. If you need to strip localizations more (e.g. for embedded
systems), you may also want to set LINGUAS and/or INSTALL_MASK.
However, if you intend to provide or use binary package, you will most
likely want to leave L10N and LINGUAS unset in order to build most
portable binary packages, and use INSTALL_MASK to transparently strip
installed localizations on the hosts using them.

For more information, please see:
https://wiki.gentoo.org/wiki/Localization/Guide
---

Of course, we'd need to update the guide to explain all three layers
in detail.

-- 
Best regards,
Michał Górny
<http://dev.gentoo.org/~mgorny/>