[Facelift] Translations (book/translations.rst) #2387

Closed
weaverryan opened this Issue Mar 30, 2013 · 3 comments

Projects

None yet

3 participants

@weaverryan
Symfony member

This ticket is about re-reading this document and giving it a facelift. No matter who you are, you have a role to play in this.

How this works:

If you read this document and find some changes, you can either comment here or (even better) create a pull request. After various people have reviewed this chapter, we'll close this issue.

What to do

Well, that depends on who you are :)

If you're newer to Symfony

Read the entry and code along with it.
a) Are there inaccuracies - code that doesn't work?
b) Are there parts that just don't understand very well?
c) Are there details that aren't explained enough?
d) Is there language that's confusing?
e) Did you fall asleep while reading it? If so, good morning! Why was it so boring?
f) Are there inconsistencies between sections?

If you know Symfony pretty darn well (or want a challenge)!

a) Are there inconsistencies between sections?
b) Do you spot anything that can be done better?
c) Are we following best practices?
d) Are there sections that are too advanced or details that should be moved into a new section to keep this readable?
e) Should some details here belong somewhere else? Like in the component documentation?
f) Are there places where we can link to other areas in the documentation to help the learner cross reference?

@inanimatt

I can't find any documentation on translating form labels. #1938 sort of helps, but it discusses creating a service to replace the built-in method, rather than documenting the builtin method itself.

I'd gladly submit a docs PR, but I don't currently know how to do it! :)

Stuff I'd like to see:

  • How Symfony's built-in form label translation works
  • Whether it's possible to use the app/console translation:update command to pick up label strings

I'll keep poking through the symfony code. If I can figure out how it all works, I'll submit a doc PR. Is the Translations doc the right place for it? (I think so, but maybe the Forms doc #2384 or a cookbook entry would be more appropriate).

@wouterj
Symfony member

Translating form labels not a topic for the book articles. The book articles are just articles which tell you all basix you need. Tips, tricks, hacks and advanced stuff are a great topic for cookbook articles.

@inanimatt

I sort of agree, but it's not at all obvious (or currently mentioned anywhere in the docs that I can see) that Symfony automatically translates form labels and does it in the default "messages" domain. Which means (at least to me) that it's not an advanced topic. It took me a couple of hours of googling before finding out that it's already being done by the framework :)

All it needs, I think, are a couple of sentences (and maybe a small example) to say something like "the default form theme already translates form labels, so you just have to add the label strings to your translation files", and maybe "the default translation domain for forms is 'messages', but you can change that by setting the translation_domain option on your form builder or custom type".

I totally agree that advanced translation stuff should be relegated to the cookbook!

@wouterj wouterj closed this Dec 23, 2013
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment