Since we will enter XWiki-related keys most of the time, we should save keystrokes and go for option 2, i.e. no "xwiki." prefix.
On 02/21/2015 03:55 AM, vinc...@massol.net wrote: > Hi Sergiu, > > On 20 Feb 2015 at 21:47:45, Sergiu Dumitriu > (ser...@xwiki.org(mailto:ser...@xwiki.org)) wrote: > >> +1, sorry for dropping the ball on that. >> >> OK for removing the product from the key, I went ahead and edited the >> proposal page. >> >> Second thoughts: what if we keep the product part for non-XWiki.org >> products bigger than a simple application, for example xclams? > > I can think of 3 different answers: > > 1) Well these rules are only for the XWiki project itself (xwiki github > org + possibly xwiki contrib org) and we cannot ask other projects to > follow them, which means they’re free to use whatever rules they want. > > 2) It’s kind of already taken care of by the star in "[module]*”: > > “ > 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.##. > “ > > xclams can be considered a big app with submodules, and could use > ##xclams.[submodule]…##. > > 3) We could decide to put back > ##product.[module]*[.section]*.element[.part]*## and for all modules > that are meant to compose or are extensions of the XWiki runtime, the > product is “xwiki”. This means all code in the xwiki organization and > most code in the xwiki-contrib org would use the “xwiki” product. But > for those doing another product (i.e a different runtime distribution - > not some flavor, since flavors are just extensions of the XWiki runtime) > then they would use their own product name. For example in the past we > had “xoffice”, “xem”, “xwatch”, “workspaces”. We would do an exception > for XE since we’re removing it in favor of simply the XWiki runtime > (we’ll remove the xwiki-enterprise repo at some point when everything is > moved into xwiki-platform). > > So idea 3) would mean that all our keys would start with “xwiki”. > > WDYT? > > Idea 3) seems the most correct to me (even though it’s a bit of a pain > to have to prefix all our translation keys with “xwiki” but it’s not > such a big deal either). > > Thanks > -Vincent > >> +1 for the deprecation strategy as well. >> >> On 02/20/2015 10:29 AM, vinc...@massol.net 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 >> >> -- >> Sergiu Dumitriu >> http://purl.org/net/sergiu >> _______________________________________________ >> devs mailing list >> devs@xwiki.org >> http://lists.xwiki.org/mailman/listinfo/devs -- Sergiu Dumitriu http://purl.org/net/sergiu _______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
