Merge pull request #14 from PepperDash/feature/update-readme

Feature/update readme

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)

epi-utilities-i18n/I18nUtility.cs

@@ -93,7 +93,7 @@ public int CurrentLanguageIndex
 
         private IEnumerable<string> 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)
             {