Implement translation on backend #267

Closed
tobscure opened this Issue Aug 27, 2015 · 14 comments

Comments

Projects
None yet
3 participants
@tobscure
Member

tobscure commented Aug 27, 2015

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.

@tobscure tobscure added this to the 0.1.0-beta.3 milestone Sep 4, 2015

@justjavac justjavac referenced this issue in justjavac/Flarum Sep 7, 2015

Open

Flarum v0.1.0 开发路线图 #3

18 of 53 tasks complete

@tobscure tobscure added the Backend label Sep 16, 2015

@franzliedke

This comment has been minimized.

Show comment
Hide comment
@franzliedke

franzliedke Sep 23, 2015

Member

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

Member

franzliedke commented Sep 23, 2015

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

@tobscure

This comment has been minimized.

Show comment
Hide comment
@tobscure

tobscure Sep 23, 2015

Member

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?

Member

tobscure commented Sep 23, 2015

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

This comment has been minimized.

Show comment
Hide comment
@franzliedke

franzliedke Sep 23, 2015

Member

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.)

Member

franzliedke commented Sep 23, 2015

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.)

@tobscure

This comment has been minimized.

Show comment
Hide comment
@tobscure

tobscure Sep 23, 2015

Member

Yep ok, makes sense.

Member

tobscure commented Sep 23, 2015

Yep ok, makes sense.

tobscure added a commit that referenced this issue Oct 15, 2015

Refactor translation and validation
We now use Symfony's Translation component. Yay! We get more powerful pluralisation and better a fallback mechanism. Will want to implement the caching mechanism at some point too. The API is replicated in JavaScript, which could definitely use some testing.

Validators have been refactored so that they are decoupled from models completely (i.e. they simply validate arrays of user input). Language packs should include Laravel's validation messages.

ref #267
@tobscure

This comment has been minimized.

Show comment
Hide comment
@tobscure

tobscure Oct 17, 2015

Member

@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)

Member

tobscure commented Oct 17, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@franzliedke

franzliedke Oct 17, 2015

Member

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?

Member

franzliedke commented Oct 17, 2015

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?

@tobscure

This comment has been minimized.

Show comment
Hide comment
@tobscure

tobscure Oct 17, 2015

Member

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).

Member

tobscure commented Oct 17, 2015

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

This comment has been minimized.

Show comment
Hide comment
@franzliedke

franzliedke Oct 17, 2015

Member

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).

Member

franzliedke commented Oct 17, 2015

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

This comment has been minimized.

Show comment
Hide comment
@dcsjapan

dcsjapan Oct 17, 2015

Member

@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.)

Member

dcsjapan commented Oct 17, 2015

@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.)

@tobscure

This comment has been minimized.

Show comment
Hide comment
@tobscure

tobscure Oct 17, 2015

Member

@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?

Member

tobscure commented Oct 17, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@dcsjapan

dcsjapan Oct 18, 2015

Member

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?

Member

dcsjapan commented Oct 18, 2015

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

This comment has been minimized.

Show comment
Hide comment
@dcsjapan

dcsjapan Oct 18, 2015

Member

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.

Member

dcsjapan commented Oct 18, 2015

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.

@tobscure

This comment has been minimized.

Show comment
Hide comment
@tobscure

tobscure Oct 18, 2015

Member

@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?

Member

tobscure commented Oct 18, 2015

@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

This comment has been minimized.

Show comment
Hide comment
@dcsjapan

dcsjapan Oct 18, 2015

Member

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.

Member

dcsjapan commented Oct 18, 2015

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.

@tobscure tobscure closed this in 43c44ef Oct 19, 2015

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment