odoo / owl

OWL: A web framework for structured, dynamic and maintainable applications
https://odoo.github.io/owl/
Other
1.1k stars 332 forks source link

Documentation for slot params shows bad example #1585

Open oomsveta opened 5 months ago

oomsveta commented 5 months ago

Currently, the documentation for slot params provides an example that uses end-user text as slot parameters. This type of content (that is, content displayed to the end user) is expected to be translated. However, Owl doesn't implement any mechanism to translate slot params. All in all, the current example from the documentation misguides developers into writing untranslatable code.

This has already happened in Odoo: someone implemented a "title" slot param exactly as shown in the documentation, thinking they did things right, yet the resulting code couldn't be translated.

In my opinion, either the documentation should be changed to provide a different example, or Owl should provide some kind of mechanism to allow translation of slot params. I don't think the latter is desirable, because slot params are not static content; they are similar to props, and I think they should be treated the same, i.e. they should not be translated.

sdegueldre commented 5 months ago

This is kind of a general problem with string literals in Owl templates. While I'm not opposed to reworking some sections of the Owl docs to avoid actively promoting this pattern, sometimes it just makes the point we're trying to make more clearly as it cuts down on the cruft. We can probably get around this issue in most places by passing technical strings instead though.

I think it would be helpful to have a big fat warning in the Odoo docs about Owl components: "String literals in template cannot be translated. You should never put any user-facing string within quotes in a template anywhere".

There is also a page dedicated to translations in the Owl docs, which could use some improvement to clarify what things won't be translated: https://github.com/odoo/owl/blob/master/doc/reference/translations.md