I think moving the framework-agnostic doc to the component section would be better

I've decided to make some really heavy changes. I moved everything from the book article to the components article and then moved framework specific information back to the book article.

I tried to do my best to create 2 articles which looks like they are written at once, but I think their are still some things that needs to get reworded. The things that needs to be done now:

• Reread the components doc to see if their are no strange things in their
• Reread the book doc to see if everything is clear
• Add introduction to the book article
• Move usage to seperate components article
• Document translation:update command

Before moving further, I'll like to get some opinions from the community (especially @weaverryan ) if we want to continue this (because heavy changes are not that nice for the translators (how ironically...)).

Hey Wouter!

Great work getting this started. In my opinion, I think this approach is worth a try, so I'd like you to finish this off. The risk is that people using the framework get a "disjointed" experience as they have to read the components documentation and then refer back to this book article also. However, the translator is one of the most straightforward documents, so this is a great one to try it on. Here are some thoughts:

1. The book should have a nice introduction chapter that talks about using the Translator in a very quick manner - e.g. show a simple example in the controller and an example of storing that translation in some configuration file. It should then outline what else you need to know, explaining that you'll want to read the component doc to find out most things and then check back on this article for other info. Basically, give people the "big picture" of what you need to know and where you'll find it.

2. Avoid doing anything really component-specific in the main translation chapter. For example, when you use the Translator directly, you'll need to interact with different "loaders" that you don't need in the framework. Let's not include these details in the main component, but instead in sub-documents so that a framework-user doesn't need to deal with those items.

How does that sound? Let me know when you'd like a further review and thanks for taking this on!

Cheers!

Thanks for your response Ryan!

I already planned to do (1). And in fact, I would like to use the 2 new code blocks created for the Form component. But that means this PR cannot get merged soon...

(2) seems not normal for me, moving component specifics into a higher level in the component docs. I think it's better to do it just the other way around: Using the component article to document loaders, constructing, ect. and create a new article which documents the usage of the Translator. In the book article, we refer to that article. What do you think?

Hi Wouter!

1. Let's not use any of the Form component things right now so we can get this merged

2. Sound perfect!

Thanks!

I haven't found any docs for the translation:update command. Probably should be done here too.

It should be part of the book article. I'll add it to the todo list

I've put some time in checking everything. To me, it looks OK now, but I'm sure we need a lot more review to get al articles fluent. If you have some time: Please review this PR.

thanks @xabbuh, love the work you are doing on the docs last weeks!

I have fixed the things I wanted to fix, let me know if you have other comments.

The only thing that needs te be done now is documenting the translation:update command.

New loader in 2.4: symfony/symfony#8534

Hey @wouterj!

I'm looking to read this fully and finally get it merged. But, I think we should update this to be based on the 2.2 branch. Especially from 2.0 to 2.1, there were locale changes with the session/request and I don't think it's worth doing this against 2.0 first and then carefully making those changes on 2.1.

These are deprecated branches, and if you need the component documentation, then you're probably either starting today (on version 2.3) or you are already a pro at using the component (since you used it originally without any docs).

You have a much better idea than I do about exactly which loaders, etc you've purposefully not included to be 2.0-compliant, so if you can rebase this against the 2.2 branch and make those changes, then I'll make sure we get this merged in :).

Thanks!

@weaverryan rebasing is a nightmare, I can imagine merging is even worse. I'll slowly fix all conflicts.

closed in favor of #2906