I'm reviewing some translation-related patches for project*. What's the right way to handle big, complicated help text messages that involve multiple paragraphs, ul or dl lists, etc?
Here's the proposal:
return t('<p>The project module makes special use of the taxonomy (category) system. A special vocabulary, %vocabulary_name, has been created automatically.</p><p>To take full advantage of project categorization, add at least two levels of terms to this vocabulary. The first level will be the basic project types, e.g., "modules", "themes", "translations".</p><p>Subterms of each of these types will be the categories that users can select to classify the projects. For example, "modules" might have sub-terms including "mail" and "XML".</ p><p>Use the <a href="@taxonomy-admin">vocabulary admin page</a> to view and add terms.</p>', array('@taxonomy-admin' => url('admin/ content/taxonomy/'. $vid), '%vocabulary_name' => $vocabulary->name));
Is one giant t() call preferred, or should this be split into a separate t() for each paragraph, and keep the HTML out of it, something like this:
return '<p>'. t('The project module makes special use of the taxonomy (category) system. A special vocabulary, %vocabulary_name, has been created automatically.', array('%vocabulary_name' => $vocabulary->name)) .'</p><p>'. t('To take full advantage of project categorization, add at least two levels of terms to this vocabulary. The first level will be the basic project types, e.g., "modules", "themes", "translations".') .'</p><p>'. t('Subterms of each of these types will be the categories that users can select to classify the projects. For example, "modules" might have sub-terms including "mail" and "XML".') .'</p><p>'. t('Use the <a href="@taxonomy-admin">vocabulary admin page</a> to view and add terms.', array('@taxonomy-admin' => url('admin/ content/taxonomy/'. $vid)) .'</p>';
??
Thanks, -Derek
Hi Derek,
I think you should look at core help texts, and see what is done there. There were times, when the monolithic t() calls were the norm, nowadays, per-paragraph, per-list-item t()s are used, both to keep HTML out of the text and to encourage people to translate the shorter text pieces, which is more comfortable when you make some change in the middle, in which case only one of the multiple strings change.
Gabor
Derek Wright wrote:
I'm reviewing some translation-related patches for project*. What's the right way to handle big, complicated help text messages that involve multiple paragraphs, ul or dl lists, etc?
Here's the proposal:
return t('<p>The project module makes special use of the taxonomy (category) system. A special vocabulary, %vocabulary_name, has been created automatically.</p><p>To take full advantage of project categorization, add at least two levels of terms to this vocabulary. The first level will be the basic project types, e.g., "modules", "themes", "translations".</p><p>Subterms of each of these types will be the categories that users can select to classify the projects. For example, "modules" might have sub-terms including "mail" and "XML".</ p><p>Use the <a href="@taxonomy-admin">vocabulary admin page</a> to view and add terms.</p>', array('@taxonomy-admin' => url('admin/ content/taxonomy/'. $vid), '%vocabulary_name' => $vocabulary->name));
Is one giant t() call preferred, or should this be split into a separate t() for each paragraph, and keep the HTML out of it, something like this:
return '<p>'. t('The project module makes special use of the taxonomy (category) system. A special vocabulary, %vocabulary_name, has been created automatically.', array('%vocabulary_name' => $vocabulary->name)) .'</p><p>'. t('To take full advantage of project categorization, add at least two levels of terms to this vocabulary. The first level will be the basic project types, e.g., "modules", "themes", "translations".') .'</p><p>'. t('Subterms of each of these types will be the categories that users can select to classify the projects. For example, "modules" might have sub-terms including "mail" and "XML".') .'</p><p>'. t('Use the <a href="@taxonomy-admin">vocabulary admin page</a> to view and add terms.', array('@taxonomy-admin' => url('admin/ content/taxonomy/'. $vid)) .'</p>';
??
Thanks, -Derek
translations mailing list translations@drupal.org http://lists.drupal.org/mailman/listinfo/translations
On Jul 13, 2007, at 11:44 PM, Gabor Hojtsy wrote:
I think you should look at core help texts, and see what is done there.
The reason I asked is because there are examples and counter-examples of both approaches in core. :( Guess I should have mentioned that in my initial question.
But, thanks for the reply. That's what I was hoping to hear, since I agree the split approach is better for everyone.
Cheers, -Derek
2007/7/14, Derek Wright drupal@dwwright.net:
[...] That's what I was hoping to hear, since I agree the split approach is better for everyone.
Except that for some language or other, it might make sense to switch order of the paragraphs, take a paragraph out, add another paragraph, or in some other way manipulate with the paragraphs to get the proper meaning. Splitting the string also risks confusion during the translation in the interface. I agree that shorter text blurbs are both easier to translate and easier to get people to translate (not as much work), but might also degrade the final outcome.
Frederik 'Freso' S. Olesen wrote:
2007/7/14, Derek Wright drupal@dwwright.net:
[...] That's what I was hoping to hear, since I agree the split approach is better for everyone.
Except that for some language or other, it might make sense to switch order of the paragraphs, take a paragraph out, add another paragraph, or in some other way manipulate with the paragraphs to get the proper meaning. Splitting the string also risks confusion during the translation in the interface. I agree that shorter text blurbs are both easier to translate and easier to get people to translate (not as much work), but might also degrade the final outcome.
Yes, it is unfortunately not a win-win situation. It seemed to be a good compromise to have one t() per paragraph/list item.
Gabor
-
Derek Wright -
Frederik 'Freso' S. Olesen -
Gabor Hojtsy