Implement translation on backend

[tobyzerner]

Currently all text output by the backend (validation messages, emails, etc.) is hardcoded in English.

What needs to be done:

• Make the Translator class adhere to Symfony's Translator interface. This is so that it can be used with Laravel's validation component.
• Add translations for Laravel's validation component messages.
• Instantiate the Translator instance in LocaleServiceProvider using the actor's preferred locale.
• Make emails translatable.

[franzliedke]

We also need to make the YAML parser resolve references, right?
Probably a good place for me to start adding some more unit tests.

[tobyzerner]

Yep, good idea. Though should we resolve the references in the YAML parser, or in the Translator (front + backend)? The former would be more DRY, the latter might save some bytes on the compiled JSON?

[franzliedke]

I think I'd like to have the references already resolved in the compiled version... so that means do it in the parser, right?
(And I think this makes sense, since it really is a feature of our specific YAML syntax.)

[tobyzerner]

Yep ok, makes sense.

[tobyzerner]

@dcsjapan How's something like this for the email translation keys:

core:
  email_activate_account_subject: Activate Your New Account
  email_activate_account_body: |
    Someone (hopefully you!) has signed up to {forumTitle} with this email address.

    If this was you, simply click the following link and your account will be activated:
    {url}

    If you did not sign up, please ignore this email.

(Read this if you're not familiar with the | syntax)

[franzliedke]

Hmm, we could also use per-language templates for the mails. Since Laravel supports sending HTML mails with text fallback, that should make things easier, no?

[tobyzerner]

I don't think language packs have any business customising the template of an email, just as they don't have any business with the templates for the rest of the app. We should keep all translations together in the same format (YAML).

[franzliedke]

Okay, fair point.
Am 17.10.2015 11:45 vorm. schrieb "Toby Zerner" notifications@github.com:

I don't think language packs have any business customising the template of
an email, just as they don't have any business with the templates for the
rest of the app. We should keep all translations together in the same
format.

—
Reply to this email directly or view it on GitHub
#267 (comment).

[dcsjapan]

@tobscure Per-language templates probably wouldn't be necessary in any case, but if the mails are going to be sent as HTML (I think the subject was brought up in the forums at some point) we'll need to have some way of inserting the language and encoding in the HTML.

As for the keys, I've been wondering about that a bit. Since we've got the forum: and admin: keys, perhaps an email: key would be another logical one to add. Then the "activate_" and so on could serve as the prefixes. (That's assuming we've got enough different types of email content that we think it'd be worth separating them into prefix chunks.)

[tobyzerner]

@dcsjapan Hmm interesting. Now that the plural syntax doesn't involve sub-keys, we could potentially use them to namespace chunks:

core:
  forum:
    change_password:
      send_button: Send Password Reset Email
      text: Click the button below and check your email for a link to change your password.
      title: => core.change_password
  email:
    activate_account:
      subject: Activate Your New Account
      body: | ...

What do you think?

[dcsjapan]

Yes, the very same idea (of using keys instead of prefixes) occurred to me while reading the Symfony docs you linked. (I didn't bring it up then because it seemed like a pretty big change, and I wanted to think it over thoroughly before suggesting it. Hard to do while stuck in a morass of translation.)

Of course, we can still add the comments above the keys to explain the chunks more fully.

It won't make much difference to the length of keys as they appear in the JS, but I do think that reducing the overall key length will make the YAML file much easier for translators to deal with.

Speaking of the plural syntax: Is it possible to arrange the variants vertically instead of horizontally in the YAML file? Most of the pluralization examples we've got now are rather short, but if we end up with a long sentence that needs pluralization, it'll be convenient if we don't have to do it all on one line. (Especially for languages like Arabic that involve a lot of different plural forms.)

Another couple questions that just occurred to me: Will it be possible for the Symfony translator to handle gender in a manner similar to pluralization? And what happens when a string ends up needing both grammatical gender and pluralization? Would we be forced to use sub-keys for gender, and if so, would that interfere with the idea of replacing prefixes with keys?

[dcsjapan]

And some further thoughts on the subject:

If grammatical gender won't pose any problems, then I'd vote to do it this way. Removing the prefixes from the keys would make it possible to change how we describe the key structure in the i18n docs:

• What we've been calling the _suffix_ could be called the _root. That makes sense, because it is the only part of the key that is mandatory. The purpose of the root is to describe _how the string is used.
• What we've been calling the _root_ could be described as an optional _prefix. The purpose of this prefix would be _to distinguish between instances of the same root (i.e., the dismiss_button versus the submit_button) _within the same sub-key_.

This implies that we don't really need prefixes at all if the same root is not reused within the same sub-key. That is, if we've got a sub-key for a dialog box that contains nothing but a title, one text, one placeholder, and one button, there's really no pressing reason to describe the strings further than that. If the translator wants a clue as to what the string says, well, he can just look at the string itself.

But if you're uncomfortable with the idea of making prefixes (formerly roots) completely optional, we can call them "optional but recommended".

The point I want to make here is that by (1) turning our prefixes in to sub-keys and (2) talking about what's left in terms of optional prefixes and mandatory roots rather than optional roots and mandatory suffixes, we can make the i18n documentation a lot less confusing, and the key naming protocol much easier for devs to deal with.

[tobyzerner]

@dcsjapan I guess long plurals could be arranged vertically using YAML's > (folded block) syntax. e.g.

key: >
  There is one potato
  |There are {count} potatoes

Would we be forced to use sub-keys for gender, and if so, would that interfere with the idea of replacing prefixes with keys?

No it shouldn't interfere. I imagine gender will look something like this:

core:
  forum:
    chunk:
      key1: hello world
      key2:
        male: hello mr. {name} 
        female: hello mrs. {name}

I agree, let's do it this way. All sounds good to me. When you have a chance, do you think you'd be able to put this into action?

[dcsjapan]

Sure! I'm trying to wrap up my translation mess at the moment. (Actually I've been hit with two acute jobs as well as the chronic one.) Once I've got that done (in perhaps a couple days or so) then I can get on it.