Issue #1054 on hold

gettext output includes restructured text

tychoish avatartychoish created an issue

When building po files, the translatable strings include restructured text directives, which should be masked or omitted in some way.

Comments (4)

  1. Robert Lehmann

    When you say “text directives,” do you mean inline markup? It is the very selling point of Sphinx i18n that it includes all inline markup, so that it can be used as locally appropriate.

    Ordering is a key argument. Let me illustrate on a quick example: The English string *coordinated* universal **time** maps to the French **temps** universel *coordonné*, ie. exactly the other way around! If we now built three translatable strings "coordinated," "universal," and "time" but kept the doctree order <bold, normal, emphasis> fixed, there would be no way to swap the original markup order.

    If there is indeed paragraph markup or other body elements ending up in the translatable strings, please give a specific, reproducable example.

  2. tychoish

    Not exactly, I mean, restructured text directives and roles:

    e.g. translators must know about our markup and avoid translating strings that are part of sphinx's internals, rather than actual content:

    e.g. :

    .. method:: foo


    the PO output includes meth, and does nothing to mask it so translators may translate the documents in such a way as to break cross references.

  3. Robert Lehmann

    What you are describing is exactly inline markup which needs to be in the translatable strings. See my previous comment for a rationale.

    You are right in that we could mask inline markup so that translators need not repeat the exact roles the original document author intended, but how would that look? First off, we would need to tag the text, so that we know which portion is inside the inline markup (eg. foo `bar` baz). Second, we would need to identify each used role in a text snippet, so that, say, :meth:`foo` is deprecated, use :func:`bar`. becomes something like :1:`foo` is deprecated, use :2:`bar`. (because, remember, we need to be able to change the order in different languages!) But then we had just reinvented ReST with a very bad representation of context.

    Now one could argue that we do not need to aim for perfection here and could do two things:

    • Instead of using :1:`foo` we could readily mask the whole string, ie. {1}, but that would fail in cases where the content of the role should be translated as well (strong, emphasis, glossary, ref, ...). Having different representations for different roles is, IMO, at best confusing.
    • For translatable strings which only have one role, we could set the default role to that one so the translator need not reference it again (so that You can :func:`frobnicate`. becomes You can `frobnicate`.)

    Both solutions are prone to losing context. I'd rather educate translators about that little bit of markup ­— it's really only inline markup — and consider both of these feature requests and not bugs in the current implementation.

    NB. Increasing the granularity is not a solution as that splits up the text into horribly confusing, small chunks and that is always a recipe for disaster.

    If you indeed meant that directives end up in the translatable strings, I could not successfully reproduce the failure you are describing.

    Say, we have the following document:

    Some text referencing :meth:`foo`.
    .. method:: foo(x, y)
       Description of foo.

    The expected translatable strings from this snippet are:

    • Some text referencing :meth:`foo`.
    • Description of foo.

    That is exactly what happens. If you feel this should be documented, please raise your voice again.

  4. Log in to comment
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
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.