sphinx / sphinx / builders / gettext.py

# -*- coding: utf-8 -*-

    The MessageCatalogBuilder class.

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

from os import path
from codecs import open
from datetime import datetime
from collections import defaultdict

from sphinx.builders import Builder
from sphinx.util import split_index_msg
from sphinx.util.nodes import extract_messages, traverse_translatable_index
from sphinx.util.osutil import safe_relpath, ensuredir, find_catalog
from sphinx.util.console import darkgreen
from sphinx.locale import pairindextypes

POHEADER = ur"""
# Copyright (C) %(copyright)s
# This file is distributed under the same license as the %(project)s package.
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: %(project)s %(version)s\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: %(ctime)s\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"


class Catalog(object):
    """Catalog of translatable messages."""

    def __init__(self):
        self.messages = []  # retain insertion order, a la OrderedDict
        self.metadata = {}  # msgid -> file, line, uid

    def add(self, msg, origin):
        if msg not in self.metadata:  # faster lookup in hash
            self.metadata[msg] = []
        self.metadata[msg].append((origin.source, origin.line, origin.uid))

class I18nBuilder(Builder):
    General i18n builder.
    name = 'i18n'
    versioning_method = 'text'

    def init(self):
        self.catalogs = defaultdict(Catalog)

    def get_target_uri(self, docname, typ=None):
        return ''

    def get_outdated_docs(self):
        return self.env.found_docs

    def prepare_writing(self, docnames):

    def write_doc(self, docname, doctree):
        catalog = self.catalogs[find_catalog(docname,

        for node, msg in extract_messages(doctree):
            catalog.add(msg, node)

        # Extract translatable messages from index entries.
        for node, entries in traverse_translatable_index(doctree):
            for typ, msg, tid, main in entries:
                for m in split_index_msg(typ, msg):
                    if typ == 'pair' and m in pairindextypes.values():
                        # avoid built-in translated message was incorporated
                        # in 'sphinx.util.nodes.process_index_entry'
                    catalog.add(m, node)

class MessageCatalogBuilder(I18nBuilder):
    Builds gettext-style message catalogs (.pot files).
    name = 'gettext'

    def finish(self):
        data = dict(
            version = self.config.version,
            copyright = self.config.copyright,
            project = self.config.project,
            # XXX should supply tz
            ctime = datetime.now().strftime('%Y-%m-%d %H:%M%z'),
        for textdomain, catalog in self.status_iterator(
                self.catalogs.iteritems(), "writing message catalogs... ",
                lambda (textdomain, _): darkgreen(textdomain),

            # noop if config.gettext_compact is set
            ensuredir(path.join(self.outdir, path.dirname(textdomain)))

            pofn = path.join(self.outdir, textdomain + '.pot')
            pofile = open(pofn, 'w', encoding='utf-8')
                pofile.write(POHEADER % data)

                for message in catalog.messages:
                    positions = catalog.metadata[message]

                    # generate "#: file1:line1\n#: file2:line2 ..."
                    pofile.write(u"#: %s\n" % "\n#: ".join("%s:%s" %
                        (safe_relpath(source, self.outdir), line)
                        for source, line, _ in positions))
                    # generate "# uuid1\n# uuid2\n ..."
                    pofile.write(u"# %s\n" % "\n# ".join(uid for _, _, uid
                        in positions))

                    # message contains *one* line of text ready for translation
                    message = message.replace(u'\\', ur'\\'). \
                                      replace(u'"', ur'\"')
                    pofile.write(u'msgid "%s"\nmsgstr ""\n\n' % message)

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.