Add documentation for OneLocBuild template

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).