Localization (#649)

* add auto-width tester

* auto resize width sample

* refinements

* add ComboBox to mixin, plus sample

* lint fix and sample update

* add other auto-layout features

* sample auto_layout updates

* auto-layout sample for 0.71

* revise auto-layout demo script

* fix issue with FCMCtrlCheckBox not storing state

* add 3-state checkbox for testing

* fix text

* add localization demo

* refactor localization to add the localization tables to the library itself.

* localize menu options of Transpose By Steps

* docs, tranposition localization

* localization of transpose

* fix a few typos

* make compatible with JW Lua

* fix typo

* Fix typos in Spanish text.

* localized enharmonic transposition scripts

* refinements to localization

* add localization for chromatic transpose

* refinements to localizing transposition

* auto_layout changes for latest RGP Lua dev branch

* Add mixin version of `__FCUserWindow::CreateChildUI` for backwards compatibility with JW Lua.

* update finenv with latest info

* one more lint warning

* transpose_by_step is working

* transpose_chromatic

* enharmonic transposing

* lint errors

* refactor folder layout for localization

* clarify comments

* checkpoint localization tool

* checkpoint localization tool

* localization tool semi-working. main things missing are plugindef support and async openai calls

* refactor sync openai calls to async

* line ending

* plugindef localization kind of working

* plugindef localization is working

* localize an example with a lot of additional menu items

* Add script group name and description

* minor updates

* Added table to list of types recognized by AddStrings method. Other mods to take advantage of this.

* refactor mixins per suggestions from ThistleSifter

* a word

* update sample localized script with latest approaches

* Bundle localizations

* address code review issues.

* in-progress checkpoint for Base localization.

* Base localization added to all src scripts and utilities. Still need to work on format strings.

* auto_layout.lua code complete

* update with latest agreed changes

* fix lint error

* add table support for multi-string arguments methods.

* changed `process_string_arguments` to `create_multi_string_proxy` so that errors are reported at the correct level, rather than in `tryfunczzz`.

* remove mobdebug

* fix small issues discovered

* Changes for `*AutoLocalized` mixin functions.

---------

Co-authored-by: Aaron Sherber <[email protected]>

Author: rpatters1

.github/actions/bundle/dist/index.js

@@ -6791,12 +6791,13 @@ const importFileBase = (name, importedFiles, fetcher) => {
     }
 };
 exports.importFileBase = importFileBase;
-const bundleFileBase = (name, importedFiles, mixins, fetcher) => {
+const bundleFileBase = (name, importedFiles, mixins, localizations, fetcher) => {
     var _a;
     const fileContents = (0, inject_extras_1.injectExtras)(name, fetcher(name));
     const fileStack = [fileContents];
     const importStack = (0, helpers_1.getAllImports)(fileContents);
     const importedFileNames = new Set();
+    importStack.push(...localizations);
     while (importStack.length > 0) {
         const nextImport = (_a = importStack.pop()) !== null && _a !== void 0 ? _a : '';
         if (importedFileNames.has(nextImport))
@@ -6821,7 +6822,16 @@ const bundleFileBase = (name, importedFiles, mixins, fetcher) => {
 };
 exports.bundleFileBase = bundleFileBase;
 const bundleFile = (name, sourcePath, mixins) => {
-    const bundled = (0, exports.bundleFileBase)(name, exports.files, mixins, (fileName) => fs_1.default.readFileSync(path_1.default.join(sourcePath, fileName)).toString());
+    const localizations = [];
+    const baseName = path_1.default.basename(name, '.lua');
+    const locPath = path_1.default.join(sourcePath, 'localization', baseName);
+    if (fs_1.default.existsSync(locPath)) {
+        localizations.push(...fs_1.default
+            .readdirSync(locPath)
+            .filter(fileName => fileName.endsWith('.lua'))
+            .map(file => `localization.${baseName}.${path_1.default.basename(file, '.lua')}`));
+    }
+    const bundled = (0, exports.bundleFileBase)(name, exports.files, mixins, localizations, (fileName) => fs_1.default.readFileSync(path_1.default.join(sourcePath, fileName)).toString());
     const parts = (0, helpers_1.getFileParts)(bundled);
     return (0, remove_comments_1.removeComments)(parts.prolog, true)
         + (0, remove_comments_1.removeComments)(parts.plugindef, false)

.github/actions/bundle/src/bundle.test.ts

@@ -40,7 +40,7 @@ describe('bundle', () => {
     }
 
     it('bundleFile', () => {
-        const bundle = bundleFileBase('a.lua', {}, [], fetcher)
+        const bundle = bundleFileBase('a.lua', {}, [], [], fetcher)
         expect(bundle).toBe(
             [
                 'package.preload["b"] = package.preload["b"] or function()',
@@ -58,17 +58,17 @@ describe('bundle', () => {
     })
 
     it('bundleFile with no imports', () => {
-        const bundle = bundleFileBase('c.lua', {}, [], fetcher)
+        const bundle = bundleFileBase('c.lua', {}, [], [], fetcher)
         expect(bundle).toBe('return {}')
     })
 
     it('ignore unresolvable imports', () => {
-        const bundle = bundleFileBase('invalid.lua', {}, [], fetcher)
+        const bundle = bundleFileBase('invalid.lua', {}, [], [], fetcher)
         expect(bundle).toBe(["local invalid = require('invalid.import')"].join('\n'))
     })
 
     it('imports all mixins', () => {
-        const bundle = bundleFileBase('mixin.lua', {}, ['mixin.FCMControl', 'mixin.FCMString'], fetcher)
+        const bundle = bundleFileBase('mixin.lua', {}, ['mixin.FCMControl', 'mixin.FCMString'], [], fetcher)
         expect(bundle).toBe(
             [
                 'package.preload["mixin.FCMControl"] = package.preload["mixin.FCMControl"] or function()',

.github/actions/bundle/src/bundle.ts

@@ -33,13 +33,16 @@ export const bundleFileBase = (
     name: string,
     importedFiles: ImportedFiles,
     mixins: string[],
+    localizations: string[],
     fetcher: (name: string) => string
 ) => {
     const fileContents = injectExtras(name, fetcher(name))
     const fileStack: string[] = [fileContents]
     const importStack: string[] = getAllImports(fileContents)
     const importedFileNames = new Set<string>()
 
+    importStack.push(...localizations)
+
     while (importStack.length > 0) {
         const nextImport = importStack.pop() ?? ''
         if (importedFileNames.has(nextImport)) continue
@@ -63,7 +66,18 @@ export const bundleFileBase = (
 }
 
 export const bundleFile = (name: string, sourcePath: string, mixins: string[]): string => {
-    const bundled: string = bundleFileBase(name, files, mixins, (fileName: string) =>
+    const localizations: string[] = []
+    const baseName = path.basename(name, '.lua')
+    const locPath = path.join(sourcePath, 'localization', baseName)
+    if (fs.existsSync(locPath)) {        
+        localizations.push(...fs
+            .readdirSync(locPath)
+            .filter(fileName => fileName.endsWith('.lua'))
+            .map(file => `localization.${baseName}.${path.basename(file, '.lua')}`)
+        )
+    }
+
+    const bundled: string = bundleFileBase(name, files, mixins, localizations, (fileName: string) =>
             fs.readFileSync(path.join(sourcePath, fileName)).toString()
         );
     const parts = getFileParts(bundled);

.github/actions/bundle/tsconfig.json

@@ -14,7 +14,9 @@
         "module": "commonjs",
         "moduleResolution": "node",
         "resolveJsonModule": true,
-        "declaration": false
+        "declaration": false,
+        "outDir": "dist",
+        "sourceMap": true
     },
     "include": [
         "**/*.ts",

.gitignore

@@ -30,3 +30,6 @@ dist/**/personal*
 # (finale_lua_menus.txt is the menu layout file used by finale_lua_menu_organizer.lua)
 finale_lua_menus.txt
 
+.github/**/dist/*.js
+!.github/**/dist/index.js
+.github/**/dist/*.map

.luacheckrc

@@ -1,5 +1,5 @@
 -- luacheck: ignore 131
-include_files = { "src/**/*.lua", "samples/**/*.lua"}
+include_files = { "src/**/*.lua", "samples/**/*.lua", "utilities/**/*.lua"}
 exclude_files = {
     "mobdebug.lua",
 }

.vscode/recommended_settings.json

@@ -14,16 +14,17 @@
         "loadall",
         "loadallforregion",
         "pairsbykeys",
+        "prettyformatjson",
         "bit32",
         "utf8",
         "socket",
         "tinyxml2",
         "xmlelements",
-        "xmlattributes",
-        "prettyformatjson"
+        "xmlattributes"
     ],
     "files.exclude": {
         "mobdebug.lua": true,
+        "dist/**": true
     },
     "editor.formatOnSave": true,
     "Lua.diagnostics.enable": false,

docs/rgp-lua.md

@@ -17,7 +17,7 @@ print ("Hello, world!")
 If you want a “Hello, world!” example that shows up as a menu option in Finale's Plug-in menu, here is a slightly more complex version:
 
 ```lua
-function plugindef()
+function plugindef(locale)
     return "Hello World", "Hello World", 'Displays a message box saying, "Hello, world!"'
 end
 
@@ -285,7 +285,6 @@ The `plugindef()` function is an optional function that **only** should do a _ma
 * Return the _plug-in name_, _undo string_ and _brief description_ to be used in the _Finale_ plug-in menu and for automatic undo blocks.
 * Define the `finaleplugin` namespace environment to further describe the plug-in (see below).
 
-
 A simple `plugindef()` implementation might look like this:
 
 ```lua
@@ -296,7 +295,36 @@ function plugindef()
 end
 ```
 
-`plugindef()` is considered to be a reserved name in the global namespace. If the script has a function named `plugindef()`, the Lua plugin may call it at any time (not only during script execution) to gather information about the plug-in. The `plugindef()` function can **NOT** have dependencies outside the function itself.
+Starting with version 0.71, _RGP Lua_ passes the user's locale code as an argument to the `plugindef` function. You can use this to localize any strings returned by the function or assigned to variables. The user's locale code is a 2-character lowercase language code followed by "_" or "-" and then a 2-digit uppercase region code. This is the same value that is returned by `finenv.UI():GetUserLocaleName()`. (See the note below detailing why the `plugindef` function cannot call `GetUserLocaleName` directly.)
+
+A localized version of the same function might look like this:
+
+```lua
+function plugindef(locale)
+    finaleplugin.RequireSelection = true
+    finaleplugin.CategoryTags = "Rest, Region"
+    local localization = {}
+    localization.en = {
+        menu = "Hide Rests",
+        desc = "Hides all rests in the selected region."
+    }
+    localization.es = {
+        menu = "Ocultar Silencios",
+        desc = "Oculta todos los silencios en la región seleccionada."
+    }
+    localization.jp = {
+        menu = "休符を隠す",
+        desc = "選択した領域内のすべての休符を隠します。",
+    }
+    -- add more localizations as desired
+    local t = locale and localization[locale:sub(1,2)] or localization.en
+    return t.menu, t.menu, t.desc
+end
+```
+
+Note that the `plugindef()` function must be *entirely* self-contained. It may not have access to any of the global namespaces that the rest of the script uses, such as `finenv` or `finale`. It *does* have access to all the standard Lua libraries. If the script has a function named `plugindef()`, the Lua plugin may call it at any time (not only during script execution) to gather information about the plug-in.
+
+`plugindef` is a reserved name in the global namespace.
 
 All aspects of the `plugindef()` are optional, but for a plug-in script that is going to be used repeatedly, the minimum should be to return a plug-in name, undo string, and short description.
 

docs/rgp-lua/finenv-properties.md

@@ -245,22 +245,23 @@ end
 
 A list of constants that define the type of message returned by `finenv.ExecuteLuaScriptItem` (if any).
 
-- `SCRIPT_RESULT` : The message was returned by Lua. It could be either an error or a value returned by the script. If it is an error, the first value returned by `ExecuteLuaScriptItem` is false.|
+- `SCRIPT_RESULT` : The message was returned by the Lua script. This is not an error message.
 - `DOCUMENT_REQUIRED` : The script was not executed because it specified `finaleplugin.RequireDocument = true` but no document was open.
 - `SELECTION_REQUIRED` : The script was not executed because it specified `finaleplugin.RequireSelection = true` but there was no selection.
 - `SCORE_REQUIRED` : The script was not executed because it specified `finaleplugin.RequireScore = true` but the document was viewing a part.
 - `FINALE_VERSION_MISMATCH` : The script was not executed because it specified a minimum or maximum Finale version and the current running version of Finale does not meet the requirement.
 - `LUA_PLUGIN_VERSION_MISMATCH` : The script was not executed because it specified a minimum or maximum Lua plugin version and the current running version of _RGP Lua_ does not meet the requirement.
 - `MISCELLANEOUS` : Other types of error messages that do not fit any of the other categories.
 - `EXTERNAL_TERMINATION` : The script was externally terminated by the user or a controlling script.
+- `LUA_ERROR` : The message is an error message returned by Lua.
 
 Example:
 
 ```lua
 local scripts = finenv.CreateLuaScriptItems()
 local success, error_msg, msg_type = finenv.ExecuteLuaScriptItem(scripts:GetItemAt(0))
 if not success then
-   if msg_type == finenv.MessageResultType.SCRIPT_RESULT then
+   if msg_type == finenv.MessageResultType.LUA_ERROR then
       -- take some action
    end
 end