From 441303ae9876da2a1a7666efcfaaaadc49d4de33 Mon Sep 17 00:00:00 2001 From: Andrew Welker Date: Fri, 12 Mar 2021 11:09:56 -0700 Subject: [PATCH 1/2] Update REadme.md --- README.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 82 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index a44d562..2ce1a17 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,91 @@ -# Internal Essentials Plugin Template (c) 2020 +# Internationalization Essentials Plugin (c) 2021 -## License +## Overview -Provided under MIT license +This plugin allows for configuration of languages using configuration files. The languages/translations are available to SIMPL Windows via an EISC Bridge, as well as internally to Essentials. -## Overview +## Configuration + +```json +{ + "key": "i18n", + "uid": 18, + "name": "I18N", + "group": "utility", + "type": "languageutility", + "properties": { + "defaultLocale": "en-us" + } +} +``` + +## Join Map + +``` +Digitals: +Join Number: 11 | JoinSpan: '150' | Description: 'Language is enabled' | Type: 'Digital' | Capabilities: 'ToSIMPL' +Analogs: +Join Number: 1 | JoinSpan: '1' | Description: 'Select Current Language & feedback' | Type: 'AnalogSerial' | Capabilities: 'ToFromSIMPL' +Serials: +Join Number: 1 | JoinSpan: '1' | Description: 'Select Current Language & feedback' | Type: 'AnalogSerial' | Capabilities: 'ToFromSIMPL' +Join Number: 11 | JoinSpan: '150' | Description: 'Start for list of supported languages' | Type: 'Serial' | Capabilities: 'ToSIMPL' +Join Number: 161 | JoinSpan: '150' | Description: 'Start for list of supported languages' | Type: 'Serial' | Capabilities: 'ToSIMPL' +Join Number: 401 | JoinSpan: '1024' | Description: 'Start Join for UI Labels' | Type: 'Serial' | Capabilities: 'ToSIMPL' +Join Number: 1501 | JoinSpan: '1024' | Description: 'Start Join for Source Labels' | Type: 'Serial' | Capabilities: 'ToSIMPL' +Join Number: 3001 | JoinSpan: '1024' | Description: 'Start Join for Destination Labels' | Type: 'Serial' | Capabilities: 'ToSIMPL' + +``` + +## Language Configuration + +Currently, language configuration is done using the spreadsheet and Powershell script located in the `language file generation` folder. + +### Editing the Excel file + +#### Metadata + +The `localeName` value for a given language should match standard locale names. Locale names can be found in t[this github repo](https://github.com/ladjs/i18n-locales). The `friendlyName` value can be displayed on a UI to allow for easier language selection. Setting the `enable` value true for a given language will allow that language to be used. All 3 of these values will be bridged to SIMPL via EISC. + +#### Language tab + +Each language should have a corresponding tab named as `{localeName}>uiLabels`, as in the example file. The PS script looks for these tabs to generate the language configuration files -Use this repo as a template when creating a new plugin for Essentials. For more information about plugins, refer to the Essentials Wiki [Plugins](https://github.com/PepperDash/Essentials/wiki/Plugins) article. +The `Join` value for an entry corresponds to the Join Number on the Touchpanel where the value will be displayed. This makes it easy to translate the VT-Pro/CH5 file to the configuration files. The `key` value should be unique for each entry in the list. The `joinNumber` column can be set using an offset from the `Join` value in a formula, or starting at 1 and incrementing. The `joinNumber` value is used to determine the placement of the text value on the bridge. The `description` value is not shown on the UI anywhere, and is used to make configuration easier, especially when using languages that don't use the western alphabet. The `displayText` value is the string that will be shown when this language is selected. UTF-16 is supported, allowing for languages such as Japanese to be displayed correctly. -## Github Actions +#### Sections -This repo contains two Github Action workflows that will build this project automatically. Modify the SOLUTION_PATH and SOLUTION_FILE environment variables as needed. Any branches named `feature/*`, `release/*`, `hotfix/*` or `development` will automatically be built with the action and create a release in the repository with a version number based on the latest release on the master branch. If there are no releases yet, the version number will be 0.0.1. The version number will be modified based on what branch triggered the build: +Each language can have sections for `uiLabels`, `sources`, and `destinations`. -- `feature` branch builds will be tagged with an `alpha` descriptor, with the Action run appended: `0.0.1-alpha-1` -- `development` branch builds will be tagged with a `beta` descriptor, with the Action run appended: `0.0.1-beta-2` -- `release` branches will be tagged with an `rc` descriptor, with the Action run appended: `0.0.1-rc-3` -- `hotfix` branch builds will be tagged with a `hotfix` descriptor, with the Action run appended: `0.0.1-hotfix-4` +### Generating the language files -Builds on the Master branch will ONLY be triggered by manually creating a release using the web interface in the repository. They will be versioned with the tag that is created when the release is created. The tags MUST take the form `major.minor.revision` to be compatible with the build process. A tag like `v0.1.0-alpha` is NOT compatabile and may result in the build process failing. +To generate the langauge configuration files, enter the following command in a terminal or powershell window + +`.\GenerateLanguageFiles.ps1 -InputFile 'C:\Users\awelker\Documents\PDEngineering\epi-utilities-i18n\language file generation\languageDefinitions.xlsx'` + +#### Optional flags + +`-OutputFilePrefix` - Add a prefix to the files output by the script +`-OutputFileSuffix` - Add a suffix to the files output by the script +`-Compress` - Generate the files with no whitespace. This will generate smaller files. + +#### Uploading Files + +The files can be uploaded to either the `user` folder or the `user\languages` folder. + +## Dependencies + +The [Essentials](https://github.com/PepperDash/Essentials) libraries are required. They are referenced via nuget. You must have nuget.exe installed and in the `PATH` environment variable to use the following command. Nuget.exe is available at [nuget.org](https://dist.nuget.org/win-x86-commandline/latest/nuget.exe). + +### Installing Dependencies + +To install dependencies once nuget.exe is installed, run the following command from the root directory of your repository: +`nuget install .\packages.config -OutputDirectory .\packages -excludeVersion`. +To verify that the packages installed correctly, open the plugin solution in your repo and make sure that all references are found, then try and build it. + +### Installing Different versions of PepperDash Core + +If you need a different version of PepperDash Core, use the command `nuget install .\packages.config -OutputDirectory .\packages -excludeVersion -Version {versionToGet}`. Omitting the `-Version` option will pull the version indicated in the packages.config file. + +## License -If you have any questions about the action, contact Andrew Welker or Neil Dorin. +Provided under [MIT License](LICENSE.md) From 855c01f7dea52cefdcbaf7f18a02603dd1eace4c Mon Sep 17 00:00:00 2001 From: Andrew Welker Date: Fri, 12 Mar 2021 11:14:16 -0700 Subject: [PATCH 2/2] fix file loading to prevent exceptions if `user\languages` doesn't exist --- epi-utilities-i18n/I18nUtility.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/epi-utilities-i18n/I18nUtility.cs b/epi-utilities-i18n/I18nUtility.cs index a732a31..f3e6471 100644 --- a/epi-utilities-i18n/I18nUtility.cs +++ b/epi-utilities-i18n/I18nUtility.cs @@ -93,7 +93,7 @@ public int CurrentLanguageIndex private IEnumerable FindLanguagesConfigurationFiles() { - var files = Directory.GetFiles(FileDirectoryB, FileName) ?? Directory.GetFiles(FileDirectoryA, FileName); + var files = Directory.GetFiles(Directory.Exists(FileDirectoryB) ? FileDirectoryB : FileDirectoryA, FileName); if (files.Length != 0) {