[Translation] Document ICU MessageFormat #11523
Conversation
| @@ -0,0 +1,123 @@ | |||
| Using Translation in Templates | |||
There was a problem hiding this comment.
Fyi: This article is simply a copy/paste from the main guide. It's far from perfect (explaining more a message formatter than a translation usage), but let's not focus on it in this PR
|
|
||
| .. _`ICU MessageFormat`: http://userguide.icu-project.org/formatparse/messages | ||
| .. _`switch statement`: https://php.net/control-structures.switch | ||
| .. _`Language Plural Rules`: http://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html |
There was a problem hiding this comment.
There are even more:
- 'spellout' which writes a number as text; i.e. '43' becomes 'forty-three'
- 'oridinal'; 43 becomes 43rd (as stated elsewhere)
- 'duration'; 43 becomes '43 sec.' (time is appearantly interpreted as seconds of duration)
|
Thanks a lot for the three very useful reviews! I'm a bit ashamed by the many grammar issues, let's say my doc skills have become a bit rusty 🙄 . Anyway, I've fixed most of them. |
|
|
||
| .. code-block:: php | ||
|
|
||
| // prints "Published at Jan 25, 2019 - 11:30 AM" |
There was a problem hiding this comment.
Maybe puts prints next to or after the echo?
There was a problem hiding this comment.
Hmm, I don't have a good reason, but I propose to leave it like it is. I don't think it's too confusing and moving them all down is quite time consuming :) Please let me know if it was confusing for you!
|
Thanks @noniagriconomie, all great catches! I've fixed them all but one (the one I commented on). |
| say_hello: 'Hello {name}!' | ||
|
|
||
| .. code-block:: xml | ||
|
|
||
| <!-- translations/messages.en.xlf --> | ||
| <!-- translations/messages+intl-icu.en.xlf --> |
There was a problem hiding this comment.
In trabslation/debug.rst we are using .xliff as extension:
.. configuration-block::
.. code-block:: xml
<!-- translations/messages.fr.xliff -->
<?xml version="1.0"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
<file source-language="en" datatype="plaintext" original="file.ext">
<body>
<trans-unit id="1">
<source>Symfony is great</source>
<target>J'aime Symfony</target>
</trans-unit>
</body>
</file>
</xliff>But in general we a re using .xlf, which one should we communicate in the docs?
There was a problem hiding this comment.
I think xlf is the recommended one. We're using it in the Symfony Demo too: https://github.com/symfony/demo/tree/master/translations
There was a problem hiding this comment.
I will change the other occurrences then in a separate PR
This PR was squashed before being merged into the 4.2 branch (closes #11523). Discussion ---------- [Translation] Document ICU MessageFormat Fixes #10604 and #11002 Thanks to the amazing work by @arjenm in the issue above, I was able to update the documentation with the new ICU MessageFormat and also create a guide explaining the format. Besides that, I did some small changes in the translation doc (including making the main guide smaller and removing duplicate parts from the component docs). While the format is a standard, ICU documentation is very difficult to read (as with all standards tbh). The JavaScript library [messageformat](https://messageformat.github.io/messageformat/page-guide) has documented the format in a simpler way, but I don't want to rely on documentation of another library (as they might suddently decide to break with the ICU standard). Thus, I decided to write our own article explaining the format in depth. I've also used Yaml as first in the configuration blocks in the message format article. This is not because I'm a huge supporter of not recommending Xliff for everyone (ref #5026, symfony/symfony#22566), but simply because it's easier to read. MessageFormat is quite complex, especially when used on a single line within lots of XML around it. Using Yaml makes examples focus on the MessageFormat, instead of the file format. Commits ------- d2736bc Yet another great review! eed64a8 Add link to usefull online editor 6ec443f Fixes after thorough reviews! 2bd7f86 Removed further usage of transchoice in the docs 0d29e3a Added documentation on the ICU MessageFormat a6dabc1 Some general fixes/improvements for translation guide
|
Thanks to everyone involved, it's now live! :) |
This PR was merged into the 3.4 branch. Discussion ---------- Use .xlf extension Refs #11523 (comment) @javiereguiluz I created a rule for this 👍 Commits ------- 519608f Use .xlf extension
Fixes #10604 and #11002
Thanks to the amazing work by @arjenm in the issue above, I was able to update the documentation with the new ICU MessageFormat and also create a guide explaining the format. Besides that, I did some small changes in the translation doc (including making the main guide smaller and removing duplicate parts from the component docs).
While the format is a standard, ICU documentation is very difficult to read (as with all standards tbh). The JavaScript library messageformat has documented the format in a simpler way, but I don't want to rely on documentation of another library (as they might suddently decide to break with the ICU standard). Thus, I decided to write our own article explaining the format in depth.
I've also used Yaml as first in the configuration blocks in the message format article. This is not because I'm a huge supporter of not recommending Xliff for everyone (ref #5026, symfony/symfony#22566), but simply because it's easier to read. MessageFormat is quite complex, especially when used on a single line within lots of XML around it. Using Yaml makes examples focus on the MessageFormat, instead of the file format.