sphinx.locale

package documentation

Locale utilities.

Unknown Field: copyright
Copyright 2007-2022 by the Sphinx team, see AUTHORS.
Unknown Field: license
BSD, see LICENSE for details.

From __init__.py:

Function get​_translation Get a translation function based on the catalog and namespace.
Function init No summary
Function init​_console Initialize locale for console.
Variable __ Undocumented
Variable admonitionlabels Undocumented
Variable pairindextypes Undocumented
Variable translators Undocumented
Variable versionlabels Undocumented
Class _​Translation​Proxy Class for proxy strings from gettext translations. This is a helper for the lazy_* functions from this module.
Function ​_lazy​_translate Used instead of _ when creating TranslationProxy, because _ is not bound yet at that time.
Function get​_translator Undocumented
Function is​_translator​_registered Undocumented
Function setlocale Update locale settings.
Variable _ Undocumented
translators: Dict[Tuple[str, str], NullTranslations] =

Undocumented

def init(locale_dirs, language, catalog='sphinx', namespace='general'):
Look for message catalogs in locale_dirs and ensure that there is at least a NullTranslations catalog set in translators. If called multiple times or if several .mo files are found, their contents are merged together (thus making init reentrant).
Parameters
locale​_dirs:List[Optional[str]]Undocumented
language:Optional[str]Undocumented
catalog:strUndocumented
namespace:strUndocumented
Returns
Tuple[NullTranslations, bool]Undocumented
def setlocale(category, value=None):

Update locale settings.

This does not throw any exception even if update fails. This is workaround for Python's bug.

For more details:

Note

Only for internal use. Please don't call this method from extensions. This will be removed in future.

Parameters
category:intUndocumented
value:Union[str, Iterable[str]]Undocumented
def init_console(locale_dir, catalog):

Initialize locale for console.

New in version 1.8.
Parameters
locale​_dir:strUndocumented
catalog:strUndocumented
Returns
Tuple[NullTranslations, bool]Undocumented
def get_translator(catalog='sphinx', namespace='general'):

Undocumented

Parameters
catalog:strUndocumented
namespace:strUndocumented
Returns
NullTranslationsUndocumented
def is_translator_registered(catalog='sphinx', namespace='general'):

Undocumented

Parameters
catalog:strUndocumented
namespace:strUndocumented
Returns
boolUndocumented
def _lazy_translate(catalog, namespace, message):
Used instead of _ when creating TranslationProxy, because _ is not bound yet at that time.
Parameters
catalog:strUndocumented
namespace:strUndocumented
message:strUndocumented
Returns
strUndocumented
def get_translation(catalog, namespace='general'):

Get a translation function based on the catalog and namespace.

The extension can use this API to translate the messages on the extension:

import os
from sphinx.locale import get_translation

MESSAGE_CATALOG_NAME = 'myextension'  # name of *.pot, *.po and *.mo files
_ = get_translation(MESSAGE_CATALOG_NAME)
text = _('Hello Sphinx!')


def setup(app):
    package_dir = os.path.abspath(os.path.dirname(__file__))
    locale_dir = os.path.join(package_dir, 'locales')
    app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)

With this code, sphinx searches a message catalog from ${package_dir}/locales/${language}/LC_MESSAGES/myextension.mo. The :confval:`language` is used for the searching.

New in version 1.8.
Parameters
catalog:strUndocumented
namespace:strUndocumented
Returns
CallableUndocumented
_ =

Undocumented

__ =

Undocumented

admonitionlabels =

Undocumented

versionlabels: Dict[str, str] =

Undocumented

pairindextypes: Dict[str, str] =

Undocumented