PLOCALE.ECLASS

Section: eclass-manpages (5)
Updated: Dec 2024
Index Return to Main Contents

NAME

plocale.eclass - convenience functions to handle localizations

DESCRIPTION

The plocale (localization) eclass offers a number of functions to more conveniently handle localizations (translations) offered by packages. These are meant to prevent code duplication for such boring tasks as determining the cross-section between the user's set LINGUAS and what is offered by the package.

Typical usage in an ebuild looks like this:

  PLOCALES="de en fr pt_BR zh_CN"
  PLOCALE_BACKUP="en"

There, PLOCALES is the list of locales that the package supports. PLOCALE_BACKUP is optional and specifies a single locale, which is used as a fallback if none of the PLOCALES matches the user's LINGUAS selection.

The eclass functions then operate on the intersection of the package's PLOCALES with the user's LINGUAS setting. (As a special case, if the LINGUAS variable is unset then all items in PLOCALES will be used, emulating the behaviour of gettext.)

In the following simple example, locale specific README files (e.g. README.de, README.en) are added to the DOCS variable:

  my_add_to_docs() {
      DOCS+=( ${1}.${2} )
  }
  plocale_for_each_locale my_add_to_docs README

A complementary function plocale_for_each_disabled_locale exists as well, which operates on the set difference of PLOCALES and LINGUAS, i.e. on the locales that the user hasn't enabled. For example, it can be used to remove unnecessary locale files.

Finally, plocale_find_changes is purely a helper function for ebuild maintenance. It can be used to scan a directory for available translations and check if the ebuild's PLOCALES are still up to date.

SUPPORTED EAPIS

7 8

FUNCTIONS

plocale_for_each_locale <function> [<args>...]: Convenience function for processing all enabled localizations. The parameter should be a function (defined in the consuming eclass or ebuild) which takes an individual locale as its (last) parameter.
Example: plocale_for_each_locale install_locale
plocale_for_each_disabled_locale <function> [<args>...]: Complementary to plocale_for_each_locale, this function will process locales that are disabled. This could be used for example to remove locales from a Makefile, to prevent them from being built needlessly.
plocale_find_changes <translations dir> <filename pre pattern> <filename post pattern>: Ebuild maintenance helper function to find changes in package offered locales when doing a version bump. This could be added for example to src_prepare.
Example: plocale_find_changes "${S}/src/translations" "${PN}_" '.ts'
plocale_get_locales [disabled]: Determine which LINGUAS the user has enabled that are offered by the package, as listed in PLOCALES, and return them. In case no locales are selected, fall back on PLOCALE_BACKUP. When the disabled argument is given, return the disabled locales instead of the enabled ones.

ECLASS VARIABLES

PLOCALES: Variable listing the locales for which localizations are offered by the package.
Example: PLOCALES="cy de el_GR en_US pt_BR vi zh_CN"
PLOCALE_BACKUP: In some cases the package fails when none of the offered PLOCALES are selected by the user. In that case this variable should be set to a default locale (usually 'en' or 'en_US') as backup.
Example: PLOCALE_BACKUP="en_US"

AUTHORS

Ben de Groot <yngwin@gentoo.org>

MAINTAINERS

Ulrich Müller <ulm@gentoo.org>

REPORTING BUGS

Please report bugs via https://bugs.gentoo.org/

FILES

plocale.eclass

This document was created by man2html, using the manual pages.
Time: 03:27:01 GMT, December 09, 2024