how is the `custom` argument used in i18n()?

nlooije

Hi, I am adding internationalization but I don't understand the function syntax of the i18n() function as described in the reference manual.

i18n( custom, token [, default] )

custom:

User defined string for this token. While it would be possible to check for this value outside the method, it is a common action to check for custom text values on objects (e.g. field configuration objects), so this is provided to simplify that logic. If not null or undefined, this value will be returned.

token:

The JS object notation string for the value that is to be loaded. For example for i18n.create.button, create.button would be given here.

The examples only use the custom argument:

editor.i18n('edit.button');

This would (and does for me) return the string 'edit.button' which is not what is needed

Instead i have to set:

editor.i18n(null, 'edit.button')

which does correctly return the string 'Update' as I would expect.

What is the usage of the custom argument?

allan

Apologies for the delay in getting back to you here. The Editor i18n method is a little odd I will admit, however, there is a sensible reason. Let's take the buttons as an example - it is possible to configure the language string for the buttons using the button's options (in which case that should take priority), or from token lookup.

This is how the create button set's up its call to create():

.create($.extend({
    buttons: config.formButtons,
    message: editor.i18n(config.formMessage , 'create.message'),
    nest: true,
    title:   editor.i18n(config.formTitle, 'create.title')
}, config.formOptions));

So if the first parameter given to i18n() is defined, it will be used, if not the token will be resolved.

At the time I wanted to save a whole lot of checks to see if there was a custom property on the button - e.g. instead of:

message: config.formMessage !== null || config.formMessage !== undefined
  ? config.formMessage
  : editor.i18n('create.message')

I just boiled it into:

message: editor.i18n(config.formMessage , 'create.message')

(note I couldn't just use a falsy check for the parameter as an empty string would be a value value).

I'm not sure this function signature is useful anywhere else, but it saves a fair amount of repetitive code. I did think about making it a secondary function, but I wasn't really expecting Editor's i18n() method to be used externally very much, unless DataTables' which is used a lot in plugins.

Does that clear things up a bit?

Allan

nlooije

Yes that clears it up and i understand the reasoning
Thank you for the explanation