From 435d4059e41c5a8061d44d9e7e925f364ffabc9c Mon Sep 17 00:00:00 2001 From: Jon Fortescue Date: Thu, 25 Mar 2021 09:55:21 -0700 Subject: [PATCH 1/3] Add documentation for OneLocBuild --- Documentation/OneLocBuild.md | 107 +++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 Documentation/OneLocBuild.md diff --git a/Documentation/OneLocBuild.md b/Documentation/OneLocBuild.md new file mode 100644 index 00000000000..19a3d7a5eab --- /dev/null +++ b/Documentation/OneLocBuild.md @@ -0,0 +1,107 @@ +# Localization with OneLocBuild in Arcade + +As of April 1, 2021, all .NET repositories will be using OneLocBuild for localization. Documentation on this system can +be found [here](https://ceapex.visualstudio.com/CEINTL/_wiki/wikis/CEINTL.wiki/107/Localization-with-OneLocBuild-Task). +This system is **not a replacement for Xliff-Tasks**; rather, it is replacing the localization team's old system called +Simple Loc. Xliff-Tasks will continue to be used in addition to OneLocBuild. + +To make OneLocBuild easier to use, we have integrated the task into Arcade. This integration is a job template +([here](/eng/common/templates/job/onelocbuild.yml)) that is described in this document. + +## LocProject.json Index File + +The core component of OneLocBuild is the LocProject.json file. This file is an index file containing references to +all of the files to localize in your repository. In order to reduce overhead for repo owners, we are auto-generating +the LocProject.json file (PowerShell script [here](/eng/common/generate-locproject.ps1)). This script and the +OneLocBuild Azure DevOps task are both wrapped in the onelocbuild.yml job template. + +The script searches your checked-in code for all localized XLF files and template JSON files. Files can be excluded +using a checked in file (/Localize/LocExclusions.json). The LocExclusions file excludes files based on simple matching. +For example, the LocExclusions.json file below will exclude everything in a directory called `tests` and any files +whose names include `test.xlf`. + +```json +{ + "Exclusions": [ + "\\tests\\", + "test.xlf" + ] +} +``` + +The selected files are then added to a generated LocProject.json file. At this point, template currently provides two options +for how to proceed. + +### Build-Time Generation + +The default way to then pass the generated LocProject.json file directly to the OneLocBuild task. This is the simpler +of the two methods and removes the overhead of needing to maintain a checked in LocProject.json file. The +LocProject.json file is emitted in build logs and as a build artifact for examination. + +### Build-Time Validation + +Alternatively, repos can opt to check in a static LocProject.json and have the script compare it against the +generated one. If they differ, the script will break the build so that a dev can update either the LocProject.json +or the LocExclusions.json file accordingly. + +Because the script can be run locally, devs can also do this validation prior to pushing their changes. + +### Custom LocProject.json Files + +Currently, the LocProject.json generation script only creates fairly uniform LocProject.json files. If your repository +requires the use of any of the more complex LocProject.json features as described in the OneLocBuild docs linked above, +the OneLocBuild template in this doc will not work and you will need to check in and maintain the LocProject.json file +manually. + +## OneLocBuild Template Parameters + +The most basic structure for calling the OneLocBuild template is: + +```yaml +jobs: +- template: /eng/common/templates/job/onelocbuild.yml + parameters: + LclSource: lclFilesfromPackage + LclPackageId: 'LCL-PACKAGE-ID' +``` + +The parameters that can be passed to the template are as follows: + +### `RepoType` +**Default Value**: `'gitHub'` + +Should be set to `'gitHub'` for GitHub-based repositories and `'azureDevOps'` for Azure DevOps-based ones. + +### `SourcesDirectory` +**Default Value**: `$(Build.SourcesDirectory)` + +This is the root directory for your repository source code. + +### `CreatePr` +**Default Value**: `true` + +When set to `true`, instructs the OneLocBuild task to make a PR back to the source repository containing the localized +files. + +### ``UseCheckedInLocProjectJson`` +**Default Value**: `false` + +When set to `true`, instructs the LocProject.json generation script to use build-time validation rather than build-time +generation, as described above. + +### ``LanguageSet`` +**Default Value**: `VS_Main_Languages` + +This defines the `LanguageSet` of the LocProject.json as described in the [OneLocBuild task documentation](https://ceapex.visualstudio.com/CEINTL/_wiki/wikis/CEINTL.wiki/107/Localization-with-OneLocBuild-Task?anchor=languageset%2C-languages-(required)). + +### `LclSource` +**Default Value**: `LclFilesInRepo` + +This passes the `LclSource` input to the OneLocBuild task as described in [its documentation](https://ceapex.visualstudio.com/CEINTL/_wiki/wikis/CEINTL.wiki/107/Localization-with-OneLocBuild-Task?anchor=languageset%2C-languages-(required)). +For most repos, this should be set to `LclFilesfromPackage`. + +### `LclPackageId` +**Default Value**: `''` + +When `LclSource` is set to `LclFilesfromPackage`, this passes in the package ID as described in the +[OneLocBuild task documentation](https://ceapex.visualstudio.com/CEINTL/_wiki/wikis/CEINTL.wiki/107/Localization-with-OneLocBuild-Task?anchor=scenario-2%3A-lcl-files-from-a-package). \ No newline at end of file From 5edf14bd783f665b9691ec1bda7edf15bea8cdb9 Mon Sep 17 00:00:00 2001 From: Jon Fortescue Date: Thu, 25 Mar 2021 16:29:49 -0700 Subject: [PATCH 2/3] Tablify --- Documentation/OneLocBuild.md | 49 ++++++++---------------------------- 1 file changed, 11 insertions(+), 38 deletions(-) diff --git a/Documentation/OneLocBuild.md b/Documentation/OneLocBuild.md index 19a3d7a5eab..a839782a900 100644 --- a/Documentation/OneLocBuild.md +++ b/Documentation/OneLocBuild.md @@ -67,41 +67,14 @@ jobs: The parameters that can be passed to the template are as follows: -### `RepoType` -**Default Value**: `'gitHub'` - -Should be set to `'gitHub'` for GitHub-based repositories and `'azureDevOps'` for Azure DevOps-based ones. - -### `SourcesDirectory` -**Default Value**: `$(Build.SourcesDirectory)` - -This is the root directory for your repository source code. - -### `CreatePr` -**Default Value**: `true` - -When set to `true`, instructs the OneLocBuild task to make a PR back to the source repository containing the localized -files. - -### ``UseCheckedInLocProjectJson`` -**Default Value**: `false` - -When set to `true`, instructs the LocProject.json generation script to use build-time validation rather than build-time -generation, as described above. - -### ``LanguageSet`` -**Default Value**: `VS_Main_Languages` - -This defines the `LanguageSet` of the LocProject.json as described in the [OneLocBuild task documentation](https://ceapex.visualstudio.com/CEINTL/_wiki/wikis/CEINTL.wiki/107/Localization-with-OneLocBuild-Task?anchor=languageset%2C-languages-(required)). - -### `LclSource` -**Default Value**: `LclFilesInRepo` - -This passes the `LclSource` input to the OneLocBuild task as described in [its documentation](https://ceapex.visualstudio.com/CEINTL/_wiki/wikis/CEINTL.wiki/107/Localization-with-OneLocBuild-Task?anchor=languageset%2C-languages-(required)). -For most repos, this should be set to `LclFilesfromPackage`. - -### `LclPackageId` -**Default Value**: `''` - -When `LclSource` is set to `LclFilesfromPackage`, this passes in the package ID as described in the -[OneLocBuild task documentation](https://ceapex.visualstudio.com/CEINTL/_wiki/wikis/CEINTL.wiki/107/Localization-with-OneLocBuild-Task?anchor=scenario-2%3A-lcl-files-from-a-package). \ No newline at end of file +| **Parameter** | **Default Value** | **Notes** | +|:-:|:-:|-| +| `RepoType` | `'gitHub'` | Should be set to `'gitHub'` for GitHub-based repositories and `'azureDevOps'` for Azure DevOps-based ones. | +| `SourcesDirectory` | `$(Build.SourcesDirectory)` | This is the root directory for your repository source code. | +| `CreatePr` | `true` | When set to `true`, instructs the OneLocBuild task to make a PR back to the source repository containing the localized files. | +| `UseCheckedInLocProjectJson` | `false` | When set to `true`, instructs the LocProject.json generation script to use build-time validation rather than build-time generation, as described above. | +| `LanguageSet` | `VS_Main_Languages` | This defines the `LanguageSet` of the LocProject.json as described in the [OneLocBuild task documentation](https://ceapex.visualstudio.com/CEINTL/_wiki/wikis/CEINTL.wiki/107/Localization-with-OneLocBuild-Task?anchor=languageset%2C-languages-(required)). | +| `LclSource` | `LclFilesInRepo` | This passes the `LclSource` input to the OneLocBuild task as described in [its documentation](https://ceapex.visualstudio.com/CEINTL/_wiki/wikis/CEINTL.wiki/107/Localization-with-OneLocBuild-Task?anchor=languageset%2C-languages-(required)). For most repos, this should be set to `LclFilesfromPackage`. | +| `LclPackageId` | `''` | When `LclSource` is set to `LclFilesfromPackage`, this passes in the package ID as described in the [OneLocBuild task documentation](https://ceapex.visualstudio.com/CEINTL/_wiki/wikis/CEINTL.wiki/107/Localization-with-OneLocBuild-Task?anchor=scenario-2%3A-lcl-files-from-a-package). | + +It is recommended that you set `LclSource` and `LclPackageId` as shown in the example above. \ No newline at end of file From 4f65f7c3f9edae243078b02e8aad07dfd629dd0c Mon Sep 17 00:00:00 2001 From: Jon Fortescue Date: Mon, 29 Mar 2021 13:49:21 -0700 Subject: [PATCH 3/3] Adjust prose --- Documentation/OneLocBuild.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Documentation/OneLocBuild.md b/Documentation/OneLocBuild.md index a839782a900..28f854e0a31 100644 --- a/Documentation/OneLocBuild.md +++ b/Documentation/OneLocBuild.md @@ -17,8 +17,8 @@ OneLocBuild Azure DevOps task are both wrapped in the onelocbuild.yml job templa The script searches your checked-in code for all localized XLF files and template JSON files. Files can be excluded using a checked in file (/Localize/LocExclusions.json). The LocExclusions file excludes files based on simple matching. -For example, the LocExclusions.json file below will exclude everything in a directory called `tests` and any files -whose names include `test.xlf`. +For example, the LocExclusions.json file below will exclude everything in a directory called `tests` and any file +which include `test.xlf` in its name. ```json { @@ -34,15 +34,15 @@ for how to proceed. ### Build-Time Generation -The default way to then pass the generated LocProject.json file directly to the OneLocBuild task. This is the simpler -of the two methods and removes the overhead of needing to maintain a checked in LocProject.json file. The -LocProject.json file is emitted in build logs and as a build artifact for examination. +**The recommended path** is to have the script pass the generated LocProject.json directly to the OneLocBuild task. +This is the simpler of the two methods and removes the overhead of needing to maintain a checked in +LocProject.json file. The LocProject.json file is emitted in build logs and as a build artifact for examination. ### Build-Time Validation -Alternatively, repos can opt to check in a static LocProject.json and have the script compare it against the -generated one. If they differ, the script will break the build so that a dev can update either the LocProject.json -or the LocExclusions.json file accordingly. +While it is **not the recommended path**, repos can instead opt to check in a static LocProject.json and have the +script compare it against the generated one. If they differ, the script will break the build so that a dev can +update either the LocProject.json or the LocExclusions.json file accordingly. Because the script can be run locally, devs can also do this validation prior to pushing their changes.