Django i18n: recommended size and formatting for {% blocktrans %} blocks?

Question

I am just getting started with Django internationalization and trying to understand the best practices for using {% blocktrans %}. Is it preferable to use one {% blocktrans %} for each paragraph, or should I have one big {% blocktrans %} that contains many paragraphs?

Having one big {% blocktrans %} is faster and makes my template look cleaner, but my concern is that:

it causes HTML tags (like <p>...</p>) to become part of the translation string
If I change one thing in one part of my huge block, the msgid would change, which seems like it could affect the other paragraphs. If I have smaller blocks, the changes would be more isolated (I suppose).
If I make a formatting change like adding/removing a newline in between paragraphs, that would change the msgid.

I am also wondering about formatting. Are there any complications to having line breaks inside a {% blocktrans %}? Or having leading spaces? e.g.:

{% blocktrans %}
    You have {{ num_messages }} messages.
    Another sentence.
{% blocktrans %}

Any recommendations are welcome.

If you have that much stuff to put in your blocktrans, you might want to consider using some content management system - not necessarily a full blown cms but at least something a bit less hardcoded. — bruno desthuilliers, Nov 22 '13 at 18:52
(The comment written by @brunodesthuilliers refers to a code sample I had in the question before editing.) — RexE, Dec 03 '13 at 17:33
@IgnacioVazquez-Abrams thanks. Does anyone have a CMS to recommend? — RexE, Dec 03 '13 at 17:43
I would use mezzanine, but using a CMS wouldn't solve your problem with i18n, trans and blocktrans are meant for TEXT only, so you shouldn't use HTML tags inside a blocktrans. — Paco Valdez, Dec 04 '13 at 21:29

score 10 · Accepted Answer · edited Jun 20 '20 at 09:12

Multiple small {% blocktrans %} blocks are beneficial for various reasons:

Each translatable string ends up in the translation files and these files should be translatable by people that speak the language. They should not have to deal with correctness of HTML tags but they should purely translate a few sentences to that language. Minor markup is fine but not the HTML of the entire page.

You can also think of it this way: the less markup in the translatable strings, the less chances for errors by translators (who may or may not have a technical background).
If a huge translation block changes then all translations need to be done again by each of the translators. If you use small translatable blocks then you can reuse most of the existing translated paragraphs / text and you only need to get updated translations for the parts that actually changed.

So to answer your question: a blocktrans tag per paragraph is a better choice. If you end up changing a paragraph then only that paragraph needs to be checked again by a translator.

Regarding whitespace and newlines: by default these will end up in the PO translation files. In Django 1.7 the blocktrans will have a trimmed option which removes whitespace and newlines (source):

This option will remove newline characters from the beginning and the end of the content of the {% blocktrans %} tag, replace any whitespace at the beginning and end of a line and merge all lines into one using a space character to separate them. This is quite useful for indenting the content of a {% blocktrans %} tag without having the indentation characters end up in the corresponding entry in the PO file, which makes the translation process easier.

Django i18n: recommended size and formatting for {% blocktrans %} blocks?

1 Answers1