On 5 Mar 2015 at 15:40:59, [email protected] ([email protected](mailto:[email protected])) wrote:
> VOTE Results: 5 +1; no 0, no -1. > > The VOTE is passed. I’ll move the page to our official doc and replace what > we currently have. Done http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HTranslationPropertyNaming links to http://dev.xwiki.org/xwiki/bin/view/Community/L10N+Conventions I’ve also updated http://dev.xwiki.org/xwiki/bin/view/Community/ApplicationDevelopmentBestPractices Thanks -Vincent > From now on, please use the new naming rule for any new translation > properties. > > Thanks > -Vincent > > > On 20 Feb 2015 at 16:29:21, [email protected] > ([email protected](mailto:[email protected])) wrote: > > > Hi devs, > > > > At the moment the VOTED rule for naming our translation properties is the > > one defined at > > http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HTranslationPropertyNaming > > > > Back in 2012 Sergiu started drafting an extended "L10N Conventions” > > document for best practices around writing translation properties at > > http://dev.xwiki.org/xwiki/bin/view/Drafts/L10N+Conventions > > > > Sergiu sent this a proposal in this mail thread: > > http://markmail.org/message/ofl23yorvxsqhn4x > > > > When Sergiu did this he didn’t realize we already had a VOTED rule for > > naming our translation properties and his proposal was in conflit with > > that. However, in this mail thread, several developers mentioned that even > > though they votes the previous naming rules they didn’t fully like it and > > preferred the one Sergiu was proposing. Several suggestion for improvements > > were also proposed. It was suggested in that thread (and Sergiu agreed) > > that he should resend a VOTE to change those established rules. Apparently > > he didn’t get the time/will to do it since I couldn’t find such a mail. > > > > In addition several developers are apparently not following the current > > rules (BAD! :)). For example in the xwiki-platform-icon-ui module, the > > Translations.xml page has the following which is NOT following the current > > rules: > > platform.icon.picker.preview=Preview with: > > platform.icon.picker.loading=Loading > > > > And most translation keys found in contrib apps at > > http://l10n.xwiki.org/xwiki/bin/view/Contrib/WebHome are also not following > > these rules (although we don’t enforce anything for contrib projects, when > > they are coded by devs from the XWiki dev team or by known contributors, it > > would be a good thing to follow the same rule, especially as, in the > > future, we want to provide a path to move from contrib sandbox to contrib > > extensions). For example I see the following type of naming: > > “polls.vote.instructions.single”. > > > > Thus, with this email I’d like to try agreeing on a new naming format and > > conventions. > > > > I propose to VOTE for making > > http://dev.xwiki.org/xwiki/bin/view/Drafts/L10N+Conventions our official > > practice with the following change for the property naming part: > > > > " > > Keys should have the following format: > > ##[module]*[.section]*.element[.part]*##, where: > > > > * ##module## is the name of the module or application being translated, > > like ##blog##, ##faq##, ##statistics##… Since a module can have submodules, > > there can be several module names. For example the SOLR Search UI is > > located in > > ##xwiki-platform-search/xwiki-platform-solr/xwiki-platform-solr-ui## and > > would have keys starting with ##search.solr.##. > > * zero, one or more ##section## parts that further refine the location of > > the string being translated; for example, a key starting with > > ##theme.colors.wizard.## refers to a text located in the //wizard// for the > > //color// part of the //theme// application (currently there are only color > > themes, but in the future we might add icon themes, layout themes, and so > > on), ##macro.python.parameter.## refers to //parameters// of the //python// > > //macro//, while a key starting with ##userdirectory.## belongs to the main > > and only section of the //user directory// application > > * ##element## identifies the main element being translated, but such an > > element could have several related parts. > > * ##part## identifies a text related to a main element, such as the > > ##label## that describes an input, the ##placeholder## found inside that > > input, the ##tooltip## that appears when hovering that input, the ##hint## > > that is displayed before the field and provides additional details about > > what it, the ##error.empty## or ##error.invalidFormat## displayed when > > there are validation errors, and so on > > > > Individual parts of the key should use **camelCase** if more than one word > > is needed to identify the element. > > “ > > > > Note that I’ve removed the ##product## part from Sergiu’s proposal (the > > reasoning is here: http://markmail.org/message/ocijlegslw45yedu). In short > > this makes it simpler to move apps around without breaking the translation > > keys. Of course it reduces the namespace and increases likelihood of > > translation clashes with user-provided extensions but I don’t think it’s > > going to be a problem and user-provided extensions should have a unique app > > name anyway. > > > > I would also point to > > http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HTranslationPropertyDeprecations > > for the deprecation part. > > > > The big question is what to do with existing translations and the only > > answer I have so far is: > > * Use the new rules when adding new translation keys (after, and if, it’s > > voted) > > * Don’t touch existing keys for now (since that would loose all > > translations) but implement the following first, and once it’s done, > > refactor existing translations over time: > > ** Add support for a deprecation section in Translations.xml’s content, > > honoured by l10n in the same way that we do it for > > ApplicationResources.properties > > ** Add the new key > > ** Move the old key to the deprecation section (in > > ApplicationResources.properties or in Translations.xml) > > ** Make the old key point to the new key, using a special syntax. For > > example: my.old.deprecated.key = @{new.shiny.key} > > > > Here’s my +1 > > > > Thanks > > -Vincent > > _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
