When should the “translatable” tag be added to a query?

Question

I noticed that a Drupal core function is using the following code:

$categories = db_select('contact', 'c')
  ->addTag('translatable')
  ->fields('c', array('cid', 'category', 'recipients', 'selected'))
  ->orderBy('weight')
  ->orderBy('category')
  ->execute()
  ->fetchAll();

When should a module add that tag to the query it is executing?
What is the effect of adding that tag? What is effectively altered, in the query object, or in the result returned by the query?

Answer 1

On it's own, that tag doesn't much (yet).

This is the so called "Dynamic data translation" feature, the idea was born on Prepare Drupal core for dynamic data translation.

Basically, you define in your hook_schema() (See contact_schema() for an example) which fields can be translated, and then add the "translatable" tag to all queries which fetch the data. Use 'translated' => TRUE' for all such columns.

Then, what is supposed to happen is that a contributed module can maintain separate tables per language for your translatable columns, automatically join these tables, and replace the selected columns with those from translated table.

However, as far as I know, nobody has yet attempted to write such a module.