[Contributing][Documentation] add order of translation formats #4112
Conversation
xabbuh
commented
Aug 10, 2014
xabbuh
commented
| Q | A |
|---|---|
| Doc fix? | yes |
| New docs? | no |
| Applies to | all |
| Fixed tickets |
| @@ -80,6 +80,7 @@ Configuration examples should show all supported formats using | |||
| * **Configuration** (including services and routing): YAML, XML, PHP | |||
| * **Validation**: YAML, Annotations, XML, PHP | |||
| * **Doctrine Mapping**: Annotations, YAML, XML, PHP | |||
| * **Translation**: XML, PHP, YAML | |||
There was a problem hiding this comment.
XML should be Xliff.
And I propose to change this order to Yaml, Xliff, Php. For these reasons:
- Xliff is far from 100% supported in Symfony
- Xliff and XML are unknown to most people, causing a lot of trouble debugging since the error messages require much experience with both Xliff and XML (for instance Improve an error message related to Xliff translation files symfony#11256 )
- Yaml is more readable and has always been the successor of PHP config files in Symfony, I don't see why we should change that here.
There was a problem hiding this comment.
I chose XML here because the code block basically is an XML code block. I don't know if it wasn't confusing for people when we'd use Xliff here since you can't xliff as a code-block argument, can you?
Changing the order is indeed a good idea though for the reasons that you listed. We would then just have to change the order of already existing examples too. But that shouldn't be big problem.
There was a problem hiding this comment.
I agree with Javier, though your points in YAML are valid. Still, XLIFF should be the recommended format.
There was a problem hiding this comment.
So, you think Xliff doesn't confuse people? Or should we mention that you have to use an xml code block, but that Xliff is the formatt?
There was a problem hiding this comment.
Sure! Xliff shouldn't be mentioned for the code-block formats. It's just an XML file, so let's mention XML only.
There was a problem hiding this comment.
What are your reasons that XLIFF should be the recommended format, @weaverryan ?
There was a problem hiding this comment.
@wouterj soon we'll explain them in detail, but for now: 1) broad support among tools used by professional translators; 2) validation (thanks to XML); 3) easy to look for translation keys (hierarchical YAML files make this "impossible").
There was a problem hiding this comment.
ping @javiereguiluz I'm hungry to learn more about this decission (after helping just another dev with XLIFF problems due to the complex XLIFF things)
The preferred order of the different translation formats in configuration blocks is Xliff, YAML, PHP. Thus, this has to be documented in the contributing section. Since the order being used before was Xliff, PHP, YAML, existing examples had to be modified accordingly.
|
I changed the order and updated examples where PHP examples are now moved after the YAML examples. |
|
Perfect :) |
…rmats (xabbuh) This PR was merged into the 2.3 branch. Discussion ---------- [Contributing][Documentation] add order of translation formats | Q | A | ------------- | --- | Doc fix? | yes | New docs? | no | Applies to | all | Fixed tickets | Commits ------- ef4dd23 add order of translation formats
