Translation methods

In the Sphinx build configuration file (, you can use translate to translate codelist CSV files and JSON Schema files:

import os
from glob import glob
from pathlib import Path

from ocds_babel.translate import translate

def setup(app):
    basedir = Path(os.path.realpath(__file__)).parents[1]
    localedir = basedir / 'locale'
    language = app.config.overrides.get('language', 'en')
    headers = ['Title', 'Description', 'Extension']

        (glob(str(basedir / 'schema' / '*-schema.json')), basedir / 'build' / language, 'schema'),
        (glob(str(basedir / 'schema' / 'codelists')), basedir / 'build' / language, 'codelists'),
    ], localedir, language, headers)

translate automatically determines the translation method to used based on filenames. The arguments to translate are:

  1. A list of tuples. Each tuple has three values:
    1. Input files (a list of paths of files to translate)
    2. Output directory (the path of the directory in which to write translated files)
    3. Gettext domain (the filename without extension of the message catalog to use)
  2. Locale directory (the path of the directory containing message catalog files)
  3. Target language (the code of the language to translate to)
  4. Optional keyword arguments to replace {{marker}} markers with values, e.g. version='1.1'

Methods are also available for translating extension.json and for translating Markdown files.

Install requirements for Markdown translation

To translate Markdown files, you must install Sphinx>=1.5 and (for now) forks of CommonMark and recommonmark, until these bugs are fixed: #225, #181, #186, #187.

Install a recent version of Sphinx with:

pip install ocds-babel[markdown]

or install a specific version like:

pip install 'Sphinx==2.2.1'

Then, install the forks of CommonMark and recommonmark:

pip install -e git+ -e git+
ocds_babel.translate.translate(configuration, localedir, language, headers, **kwargs)[source]

Writes files, translating any translatable strings.

For translated strings in schema files, replaces {{lang}} with the language code. Keyword arguments may specify additional replacements.

ocds_babel.translate.translate_codelist(io, translator, headers=[], **kwargs)[source]

Accepts a CSV file as an IO object, and returns its translated contents in CSV format.

ocds_babel.translate.translate_codelist_data(source, translator, headers=[], **kwargs)[source]

Accepts CSV rows as an iterable object (e.g. a list of dictionaries), and returns translated rows.

ocds_babel.translate.translate_schema(io, translator, **kwargs)[source]

Accepts a JSON file as an IO object, and returns its translated contents in JSON format.

ocds_babel.translate.translate_schema_data(source, translator, **kwargs)[source]

Accepts JSON data, and returns translated data.

ocds_babel.translate.translate_extension_metadata(io, translator, lang='en', **kwargs)[source]

Accepts an extension metadata file as an IO object, and returns its translated contents in JSON format.

ocds_babel.translate.translate_extension_metadata_data(source, translator, lang='en', **kwargs)[source]

Accepts extension metadata, and returns translated metadata.