english removal: notes: lj_dev

Here're some notes of interest to those who are helping out with the great English-removal project. If you want to help, but don't know what this project is about, go read the linked entry first. This entry updates some obsolete information, explains new features and discusses a naming scheme for translation codes.

If you want to submit a patch which removes English from some BML file(s), send it to me (avva@livejournal.com), don't send it to Brad. I carefully review submissions, fix errors, bring some unity to translation codes and in particular to the global codes, and so on. All patches sent to me so far have been reviewed, corrected where needed and sent to Brad. Some of them have already been committed, others will be very soon.
If you want to work on a large BML file or a group of related files, ask me first if someone isn't already working on it, to avoid duplication of effort.
There are three ways of invoking the translation engine, only two of which are described in the original post by Brad (because the third didn't exist then):
- The BML tag: (=_ML name _ML=). Use this, and only this, outside _CODE tags, in other words, outside Perl code in BML files.
- The BML::ml() function. Use it in Perl code only when the translation item requires a parameter to be passed to it (and then BML::ml() is the only way to do that).
- The new tied hash: $ML{'name'} . "Tied" means that it's not really a hash; when you access it, some code is run which is equivalent to calling BML::ml() . But from a syntactic point of view $ML is much easier and simpler and should be used everywhere in Perl code unless there's a need for parameters. Also, it can and should be used in double-quoted strings:
  
  $body.="some html...$ML{'somename'}more html...";
All three methods support names which start with a dot, and then the path to the current BML file is automatically appended to them. Moreover, in files which contain strings, use the directive

==BML: /community/create.bml

(for example),

and then after this line all strings which start with a dot are also prefixed with the name of the BML file.
Take a look at some of the committed patches (for example, this one) to get a feel for it.
Naming of translation items. Have a look at bin/upgrading/en.dat and use common global items already stored there ("global" means they don't start with a dot and so aren't tied to any particular source file); this is especially important for common error codes, named under error.*

In your local string files, start all errors with .error.* When several strings relate to the same part of the page or the same functionality, group them together with the same prefix, but don't overdo it by producing annoyingly long names. Again, look at committed patches to see how others dealt with the naming issues. It's not really important that everyone conform to some rigid naming scheme, because these names are really just internal labels; so we're not trying to enforce any particular scheme. But following some common sense and common guidelines established in practice by others makes source more readable and maintainable in the future. In particular, strive for internal consistency inside every source file.
Feel free to suggest new global items in your patches. But also please remember that many strings which may appear truly global to you really shouldn't be. As an illuminating example, consider the heading "Success" which is used as the title of many BML pages after a successful action. It turns out that some languages simply lack a neutral suitable noun such as 'Success' that could be used everywhere; direct equivalents sound forced or ridiculous. Therefore every page which uses such a heading should store it in a separate local item, so that translators to various languages could offer more specific and idiomatic translations for each case.
Have fun ;)

english removal: notes

"Invalid password" when calling login method over XML-RPC

cl-journal livejournal client

SessionGenerate and ljloggedin

Error