How to write Drupal translatable interfaces

Why document this in the upgrade handbook? I'd like to get a "How to write Drupal translatable interfaces" guide done for module and theme authors, and actually kicked this off with a cheat sheet as a quick takeaway. Maybe you can help with tips on revising the cheat sheet. I also hope to make better documentation for module and theme writers on drupal.org and/or published in some more compact form. The cheat sheet idea itself came to let the guys understand that this is not hard, there are simple rules to follow.

Moving to the developer guide.

Indeed, it could be. Care to submit the idea on groups.drupal.org? (Handbook pages on drupal.org would be the deliverables).

I've love to make this a GHOP task, but we need more details on what exactly such a document would need to cover. Please see the guidelines at http://code.google.com/p/google-highly-open-participation-drupal/wiki/Ho...

A couple of useful links:

http://hojtsy.hu/blog/2007-nov-15/make-jump-ensure-your-drupal-modules-a...

http://api.drupal.org/api/function/t/6 and http://api.drupal.org/api/function/t/5

When this handbook page has been written, there should be links to it from the handbook pages http://drupal.org/node/296338 (which currently links to this issue) and http://drupal.org/node/254214.

Changed the component to reflect the new component categorization. See http://drupal.org/node/301443
-nielsbom

http://drupal.org/node/312523 is the coder module integration issue for potx module which would benefit greatly from this page to point to with potx error messages.

Yes, even ignoring coder's need for it, I think such a documentation would hugely benefit the developers. For the most part, I think developers just don't know that they shouldn't be passing variables, etc, to t(). However, as well as documenting what shouldn't be done, it should also document best practises. I'm specifically thinking of translating dynamic variables here.

Going to make some time for this next week. Expect a big page or pages coming out of my keyboard then.

I just found this handbook page: Module developer's guide > Multilingual support, which covers some of this topic.

zirvap: It is a far cry, from what should be documented unfortunately. (Yes, I am working on this but the comprehensiveness I am trying to achieve does not let me go forward fast enough.

Ok, instead of sitting on what we have any longer, I've started to add the three pages I wrote to the handbook: http://drupal.org/book/export/html/322729

This forms a new "Localization API" section in the Drupal APIs section of the documentation. The page linked by zirvap is basically about translating user input, not making it possible to translate the interface of a module which is the issue at hand. Feedback is welcome. I have lots of more pages in the pipeline to be written. Next up is a page titled "Dynamic or static links and HTML in translatable strings". Lots of fun there.

Huh, I think the guide is almost complete :) It has the following subpages:

• Two backends for translations: installer and runtime
• Dynamic strings with placeholders
• Dynamic or static links and HTML in translatable strings
• Formatting numbers, dates/times, sizes and intervals with localization
• Strings at well known places: built-in menus, permissions, log messages and .info files
• Translating strings in JavaScript

I've worked on this quite some this last week and over this weekend. I've also double checked, validated and included my cheat sheet on the intro page, since it is IMHO the best quick summary of all the little things involved. I say this is almost complete, as I see at least one thing missing: translating emails. That is a bit special, since it requires handling the target user language. Otherwise I think this is a pretty decent guide now as it is, and will serve great to link to from potx coder error messages as well as hass pointing all kinds of developers to these pages while submitting bugs :)

Feedback is welcome!

Ha, yeah, of course I'd also like to include a "teaser page" on translating user input, which would basically explain that t() should not be used for that in general, and Drupal 6 provides such an API but i18nstrings is the module which implements it. Just to set things straight as people would ask this anyhow a lot of times :)

1. My thinking was that basically hook_schema() is run in install time to create the database tables. t() uses the database, and therefore t() should not be used in functions which fiddle with the database (such as update functions and the schema hook). Well, actually, the schema hook itself does not do anything, but you probably get the idea that it is used to build up the database.

Interestingly, system.install uses t() in its schema hook. Well, since when it is installed, locale module will surely not be installed, it should not be a problem. Also locale.install uses t(). I think it works because when the schema hook is invoked, the module is not yet installed, so the database is not looked at. After that, the database can be looked at for t() stuff. Well, we can reverse on this and suggest using t() in schema hooks, it does indeed work.

2. Well, Drupal's locale module uses @content-help, @add-language and friends. Token module, one of the most common base modules reused by a miriad of other modules also uses %site-name, %user-mail and so on. I wrote into the docs, that Drupal core itself is inconsistent in this, but the hyphen is generally suggested to be used, not the underscore. The hyphen is way easier for translators to actually notice in the text and not translate the continuation of the placeholder as if there were words there. Compare %site-name to %site_name.

3. If you'd use it like <em>@value</em> then it is indeed a bad idea. If you just emphasize some part of the string which is not a placeholder, such as Users think this is a <em>good thing</em>., then I say use it. I wrote the text to suggest using inline markup but avoid using block markup. It should possibly be expanded to also say complex inline markup is discouraged (such as styles, onlick and whatever other nastiness :)

My original writing included suggestions for format_plural() usage to use @count in the singular parameter as well. Since that make no sense given that translations in need of @count there could just include count, and even the Arabic example I've provided does not use @count in all cases, I've gone back to suggesting the simpler English form: http://drupal.org/node/323072/revisions/view/374597/374817

Made the same change for the JS translation page: http://drupal.org/node/323109/revisions/view/374642/374819

Following on the above suggestion from hass, I've updated the docs to say that the schame hook should use t() instead of $t(). Also, documented that update functions just should not use this API. http://drupal.org/node/322731/revisions/view/374097/375095

From where would $t() get translatable strings in the update process?

st() was designed to be used in the installer and is therefore loading in ONE .po file from the /profiles directory macthing for the current profile and language when installing Drupal. It does not load anything from the modules themselves.

Hrm, is this issue still pending or is it pretty much done and further changes can be made as needed?

@add1sun this seems to be pretty much resolved to me - the handbook pages have been updated, and as mentioned, one .po loads with the install (and others can be downloaded later if needs be) so the documentation stands for that.

marking as fixed (please open new issues for any smaller fixes)