refactor: update translate macro to reuse lingo macro

core/wiki/macros/lingo.tid

@@ -1,32 +1,23 @@
 title: $:/core/macros/lingo
-tags: $:/tags/Macro
+tags: $:/tags/Global
 
-\define lingo-base()
+<!-- Note that lingo-base should end with a trailing slash character -->
+\procedure lingo-base()
 $:/language/
-\end
+\end lingo-base
 
-\define lingo(title)
-{{$(lingo-base)$$title$}}
-\end
-
-\procedure translate(key, lingo-base-fallback, mode:block)
-<!-- Allow assign lingo-base in caption field by accepting the lingo-base-fallback param. -->
-\function target-lingo-base()
-[<lingo-base-fallback>!is[blank]else<lingo-base>]
-\end target-lingo-base
-
-\function add-lang-suffix(base)
-[[$:/language]get[text]get[name]else[en-GB]]
-+[addprefix<base>]
-\end add-lang-suffix
-
-<!-- Allow lingo-base to have or not have / ending slash, for better dev experience. Then add, e.g. `en-GB/Key` after it. -->
-\function lingo-target()
-[function[target-lingo-base]suffix[/]]
-:then[function[target-lingo-base]]
-~[function[target-lingo-base]addsuffix[/]]
-:map[function[add-lang-suffix],<currentTiddler>addsuffix[/]addsuffix<key>]
-\end lingo-target
-
-<$transclude $tiddler=<<lingo-target>> $mode=<<mode>> />
-\end
+\procedure lingo(title,override-lingo-base)
+<!-- Get the parse mode used to invoke this procedure -->
+<$parameters $parseMode="parseMode">
+	<!-- Compute the lingo-base-->
+	<$let active-lingo-base={{{ [<override-lingo-base>!match[]else<lingo-base>] }}}>
+		<!-- First try the old school <active-lingo-base><title> format -->
+		<$transclude $tiddler={{{ [<active-lingo-base>addsuffix<title>] }}} $mode=<<parseMode>>>
+			<!-- If that didn't work, try the new <lingo-base><langcode>/<title> format -->
+			<$let language-code={{{  [[$:/language]get[text]get[name]else[en-GB]] }}}>
+        <$transclude $tiddler={{{ [<active-lingo-base>addsuffix<language-code>addsuffix[/]addsuffix<title>] }}} $mode=<<parseMode>>/>
+			</$let>
+		</$transclude>
+	</$let>
+</$parameters>
+\end lingo

editions/tw5.com/tiddlers/macros/LingoMacro.tid

@@ -7,11 +7,31 @@ type: text/vnd.tiddlywiki
 
 The <<.def lingo>> [[macro|Macros]] relates to the translation of ~TiddlyWiki's user interface into other languages. It returns a piece of text in the user's currently selected language.
 
-Translatable text is supplied by language plugins containing tiddlers with specific titles that start with `$:/language/`. If you want to use l10n (localization) strings outside of the language plugins, you can use [[translate Macro]] instead.
+Translatable text is supplied by：
 
-!! Parameters
+# Language plugins
+# Any l10n (localization) strings outside of the language plugins
+
+!! Language plugins
+
+You can directly pass title to `lingo` macro, when there is a language plugin containing a tiddler with such title that start with `$:/language/`. 
 
 ;title
 : The title of the shadow tiddler that contains the text. The prefix `$:/language/` is added automatically
 
-<<.macro-examples "lingo">>
+<<.macro-examples "lingo (for language plugin)">>
+
+!! Any l10n strings
+
+To translate any text that directly placed in user's wiki, instead of in a language plugin, you can set the `lingo-base` variable to teach <<.def lingo>> macro the place to look for.
+
+!!! Parameters
+
+;key
+: The last part of title of the tiddler that contains the text. The `<<lingo-base>>` prefix and current language name prefix is added automatically
+;lingo-base-fallback
+: Optional lingo-base when it is not possible to define `lingo-base` variable (for example, when using this macro in the caption field), you can set the lingo base by passing this parameter
+
+<<.macro-examples "lingo (for custom base)">>
+
+{{lingo Macro (file structure)}}

editions/tw5.com/tiddlers/macros/examples/lingo Macro (custom base examples).tid

@@ -0,0 +1,21 @@
+created: 20231028120432257
+modified: 20240206113509050
+tags: [[lingo Macro]] [[Macro Examples]]
+title: lingo (for custom base) Macro (Examples)
+type: text/vnd.tiddlywiki
+
+\define lingo-base() lingo Macro (custom base examples)/
+
+Given the `\define lingo-base() lingo Macro (custom base examples)/`, this example shows the localizaion key `ExampleKey` being translate to the text in [[lingo Macro (custom base examples)/en-GB/ExampleKey]]:
+
+<$macrocall $name=".example" n="1" eg="""<<lingo ExampleKey>>"""/>
+
+This example shows the `lingo-base` can be set as second parameter:
+
+<$macrocall $name=".example" n="2" eg="""<<lingo ExampleKey "lingo Macro (custom base examples)/">>"""/>
+
+When use lingo macro in a [[Inline Mode WikiText]] like [[list|Lists in WikiText]] or [[title|Headings in WikiText]], the parse mode will be inline, so translated text will be inlined too.
+
+<$macrocall $name=".example" n="3" eg="""# <<lingo ExampleKey>>"""/>
+
+<$macrocall $name=".example" n="4" eg="""!! <<lingo ExampleKey>>"""/>

editions/tw5.com/tiddlers/macros/examples/translate Macro (Examples)_en-GB_ExampleKey.tid → editions/tw5.com/tiddlers/macros/examples/lingo Macro (custom base examples)_en-GB_ExampleKey.tid

@@ -1,7 +1,8 @@
 created: 20231028120526948
-modified: 20231028123420761
-title: translate Macro (Examples)/en-GB/ExampleKey
+modified: 20240206113155142
+title: lingo Macro (custom base examples)/en-GB/ExampleKey
+type: text/vnd.tiddlywiki
 
-This is the translated text of key "~ExampleKey" under lingo-base `translate Macro (Examples)`
+This is the translated text of key "~ExampleKey" under lingo-base `lingo Macro (custom base examples)/` (don't forget the tailing slash `/`)
 
 And is multi-line, if it is translated in the block mode by default. (Become single line if set to inline mode.)

editions/tw5.com/tiddlers/macros/examples/lingo Macro (file structure).tid

@@ -0,0 +1,71 @@
+created: 20231028120432257
+modified: 20240206122408606
+tags: [[lingo Macro]] [[Macro Examples]]
+title: lingo Macro (file structure)
+
+!! Example file structure for [[TiddlyWiki on Node.js]]
+
+!!! Suggested file structure
+
+When developing a plugin, you may want to organize your language files like this on the file system as [[MultiTiddlerFiles]]:
+
+```tree
+├── language
+│   ├── en-GB
+│   │   ├── Translations.multids
+│   │   └── SomeLongText.tid
+│   └── zh-Hans
+│       ├── Translations.multids
+│       └── SomeLongText.tid
+├── other files
+└── plugin.info
+```
+
+!!! Define Multiple Translations in One Tiddler
+
+And the content of `language/en-GB/Translations.multids` may looks like this:
+
+```multids
+title: $:/plugins/yourName/pluginName/language/en-GB/
+
+OpenInteractiveCard: Open Interactive Card
+OpenStaticCard: Open Static Card
+```
+
+Later you can use it like:
+
+```tid
+title: someTiddler
+caption: <<lingo OpenStaticCard "$:/plugins/yourName/pluginName/language/">>
+
+\define lingo-base() $:/plugins/yourName/pluginName/language/
+\whitespace trim
+
+<<lingo OpenInteractiveCard>>
+```
+
+!!! Define Long Text in a regular Tiddler
+
+You can also use a regular tiddler for long text, like `SomeLongText.tid` in the example above, to store a multi-paragraph long text:
+
+```tid
+title: $:/plugins/yourName/pluginName/language/en-GB/SomeLongText
+
+!!! SubTitle
+
+This is a long text.
+```
+
+Later you can use it like:
+
+```tid
+title: someTiddler
+
+\define lingo-base() $:/plugins/yourName/pluginName/language/
+
+!! <<lingo "OpenInteractiveCard">>
+
+<<lingo SomeLongText>>
+```
+
+Note that lingo macro will use the [[parse mode|WikiText Parser Modes]] in the current position where this procedure is invoked.

editions/tw5.com/tiddlers/macros/examples/lingo.tid → editions/tw5.com/tiddlers/macros/examples/lingo Macro (language plugin examples).tid

@@ -1,7 +1,7 @@
 created: 20150221151358000
 modified: 20150221160113000
 tags: [[lingo Macro]] [[Macro Examples]]
-title: lingo Macro (Examples)
+title: lingo (for language plugin) Macro (Examples)
 type: text/vnd.tiddlywiki
 
 This example shows the text used as the basis for the title of a newly created tiddler: