Re: [xwiki-devs] [VOTE] New Translation property naming rules (RESULT)
On 5 Mar 2015 at 15:40:59, vinc...@massol.net (vinc...@massol.net(mailto:vinc...@massol.net)) 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, vinc...@massol.net (vinc...@massol.net(mailto: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
Re: [xwiki-devs] [VOTE] New Translation property naming rules
+1 for the proposed changes. For me it's easier to scan and understand where the key is used if the parts (modules, sections) are separated by a dot, rather than using only camel case. Thanks, Marius On Fri, Feb 20, 2015 at 5:29 PM, vinc...@massol.net 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
Re: [xwiki-devs] [VOTE] New Translation property naming rules
+1 and same comment than Marius On Fri, Feb 27, 2015 at 11:22 AM, Marius Dumitru Florea mariusdumitru.flo...@xwiki.com wrote: +1 for the proposed changes. For me it's easier to scan and understand where the key is used if the parts (modules, sections) are separated by a dot, rather than using only camel case. Thanks, Marius On Fri, Feb 20, 2015 at 5:29 PM, vinc...@massol.net 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
Re: [xwiki-devs] [VOTE] New Translation property naming rules
+1 for having a standard. I had no problem with the current standard. In the end it is just an ID, not an API. What is more important to me is ID collisions. We have the habit of using translation documents with 'Wiki' scope pretty much everywhere. Maybe it would be smarter to see translation objects/documents like SSX or JSX objects that are generally used 'On Demand', more importantly now that we want to drop the prefix (something which I like, but also see potential problems with). Of course, we can not do anything about java translations (ApplicationResources.properties). In any case, I think we are just asking for it when it comes to translation key collisions and we are bound to see problems in the future, unless we start taking it into consideration (solutions, tools to debug translation problems, etc.). An example that comes to my mind is that we have 2 forum applications in e.x.o *and* a bulletin board application (which is basically a 3rd forum app). I`m +1 for the proposed changes (specially since people seem to like dots in their translation keys and because of the ease of moving code around, introduced by the removal of the product). Thanks, Eduard On Mon, Feb 23, 2015 at 11:46 AM, vinc...@massol.net vinc...@massol.net wrote: On 23 Feb 2015 at 10:32:47, Guillaume Louis-Marie Delhumeau ( gdelhum...@xwiki.com(mailto:gdelhum...@xwiki.com)) wrote: 2015-02-20 16:29 GMT+01:00 vinc...@massol.net : 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 What is wrong with that? Simply that it was not following our naming rule, see http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HTranslationPropertyNaming Dots are not allowed in the property name? picker.preview should have been called pickerPreview? What if the property name is long, such as platform.wiki.users.join.request.cancelYes? It should have been platform.wiki.usersJoinRequestCancelYes? yes, something like (which I agree is not that nice - it works better for config properties than for translating UI elements): platform.wiki.yesLabelCancelUserJoinRequest or platform.wiki.cancelUserJoinRequestYesLabel Now this new VOTE goes in your direction but the point is that it’s hard to have common naming rules so even if someone doesn’t like the new proposal, when it’s voted we should all try to follow it (or raise it if there are issues). Thanks -Vincent 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
Re: [xwiki-devs] [VOTE] New Translation property naming rules
2015-02-20 16:29 GMT+01:00 vinc...@massol.net vinc...@massol.net: 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 What is wrong with that? Dots are not allowed in the property name? picker.preview should have been called pickerPreview? What if the property name is long, such as platform.wiki.users.join.request.cancelYes? It should have been platform.wiki.usersJoinRequestCancelYes? 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
Re: [xwiki-devs] [VOTE] New Translation property naming rules
On 23 Feb 2015 at 10:32:47, Guillaume Louis-Marie Delhumeau (gdelhum...@xwiki.com(mailto:gdelhum...@xwiki.com)) wrote: 2015-02-20 16:29 GMT+01:00 vinc...@massol.net : 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 What is wrong with that? Simply that it was not following our naming rule, see http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HTranslationPropertyNaming Dots are not allowed in the property name? picker.preview should have been called pickerPreview? What if the property name is long, such as platform.wiki.users.join.request.cancelYes? It should have been platform.wiki.usersJoinRequestCancelYes? yes, something like (which I agree is not that nice - it works better for config properties than for translating UI elements): platform.wiki.yesLabelCancelUserJoinRequest or platform.wiki.cancelUserJoinRequestYesLabel Now this new VOTE goes in your direction but the point is that it’s hard to have common naming rules so even if someone doesn’t like the new proposal, when it’s voted we should all try to follow it (or raise it if there are issues). Thanks -Vincent 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
Re: [xwiki-devs] [VOTE] New Translation property naming rules
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##…
Re: [xwiki-devs] [VOTE] New Translation property naming rules
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
Re: [xwiki-devs] [VOTE] New Translation property naming rules
+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? +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
[xwiki-devs] [VOTE] New Translation property naming rules
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
