References

Commands

Type sphinx-intl without arguments, options to show command help.

sphinx-intl

sphinx-intl [OPTIONS] COMMAND [ARGS]...

Options

-c, --config <FILE>

Sphinx conf.py file to read a locale directory setting.

-t, --tag <TAG>

Pass tags to conf.py, as same as passed to sphinx-build -t option.

Environment variables

SPHINXINTL_TAG

Provide a default for -t

build

Build specified language’s po files into mo.

sphinx-intl build [OPTIONS]

Options

-d, --locale-dir <DIR>

locale directories that allow comma separated string. This option override locale_dir in conf.py setting if provided. Default is empty list.

Default:

locales

-o, --output-dir <DIR>

mo files directory where files are written. Default is to match the ‘–locale-dir’ path.

-l, --language <LANG>

Target language to update po files. Default is ALL.

Environment variables

SPHINXINTL_LOCALE_DIR

Provide a default for -d

SPHINXINTL_OUTPUT_DIR

Provide a default for --output-dir

SPHINXINTL_LANGUAGE

Provide a default for -l

create-transifexrc

Create $HOME/.transifexrc (deprecated)

sphinx-intl create-transifexrc [OPTIONS]

Options

--transifex-token <TOKEN>

Required Your transifex token. (DEPRECATED)

Environment variables

SPHINXINTL_TRANSIFEX_TOKEN

Provide a default for --transifex-token

create-txconfig

Create ./.tx/config

sphinx-intl create-txconfig [OPTIONS]

stat

Print statistics for all po files.

sphinx-intl stat [OPTIONS]

Options

-d, --locale-dir <DIR>

locale directories that allow comma separated string. This option override locale_dir in conf.py setting if provided. Default is empty list.

Default:

locales

-l, --language <LANG>

Target language to update po files. Default is ALL.

Environment variables

SPHINXINTL_LOCALE_DIR

Provide a default for -d

SPHINXINTL_LANGUAGE

Provide a default for -l

update

Update specified language’s po files from pot.

For examples:
sphinx-intl update -l de -l ja
sphinx-intl update -l de,ja
sphinx-intl update [OPTIONS]

Options

-d, --locale-dir <DIR>

locale directories that allow comma separated string. This option override locale_dir in conf.py setting if provided. Default is empty list.

Default:

locales

-p, --pot-dir <DIR>

pot files directory which is generated by sphinx. Default is ‘pot’ directory under ‘–locale-dir’ path.

-l, --language <LANG>

Target language to update po files. Default is ALL.

-w, --line-width <WIDTH>

The maximum line width for the po files, 0 or a negative number disable line wrapping

Default:

76

Environment variables

SPHINXINTL_LOCALE_DIR

Provide a default for -d

SPHINXINTL_POT_DIR

Provide a default for --pot-dir

SPHINXINTL_LANGUAGE

Provide a default for -l

SPHINXINTL_LINE_WIDTH

Provide a default for -w

update-txconfig-resources

Update resource sections of ./.tx/config.

sphinx-intl update-txconfig-resources [OPTIONS]

Options

--transifex-organization-name <ORGANIZATION-NAME>

Required Your transifex organization name.

--transifex-project-name <PROJECT-NAME>

Required Your transifex project name.

-d, --locale-dir <DIR>

locale directories that allow comma separated string. This option override locale_dir in conf.py setting if provided. Default is empty list.

Default:

locales

-p, --pot-dir <DIR>

pot files directory which is generated by sphinx. Default is ‘pot’ directory under ‘–locale-dir’ path.

Environment variables

SPHINXINTL_TRANSIFEX_ORGANIZATION_NAME

Provide a default for --transifex-organization-name

SPHINXINTL_TRANSIFEX_PROJECT_NAME

Provide a default for --transifex-project-name

SPHINXINTL_LOCALE_DIR

Provide a default for -d

SPHINXINTL_POT_DIR

Provide a default for --pot-dir

Environment Variables

All command-line options can be set with environment variables using the format SPHINXINTL_<UPPER_LONG_NAME>. Dashes (-) have to be replaced with underscores (_).

For example, to set the languages:

export SPHINXINTL_LANGUAGE=de,ja

This is the same as passing the option to sphinx-intl directly:

sphinx-intl <command> --language=de --language=ja

Sphinx conf.py

Add below settings to sphinx document’s conf.py if they do not exists:

locale_dirs = ['locale/']   #for example
gettext_compact = False     #optional

Makefile / make.bat

make gettext will generate pot files into _build/gettext directory, however it is much convenient if pot files are generated into the locale/pot directory. You can achieve this by replacing _build/gettext with locale/pot in your Makefile and/or make.bat that was generated by sphinx-quickstart.