feat: t macro and docs

core/wiki/macros/lingo.tid

@@ -8,3 +8,15 @@ $:/language/
 \define lingo(title)
 {{$(lingo-base)$$title$}}
 \end
+
+\define t(key,lingo-base-fallback:"")
+<!-- Allow assign lingo-base in caption field by accepting the lingo-base-fallback param. -->
+<$set name="lingoBaseWithFallback" value="$lingo-base-fallback$" emptyValue=<<lingo-base>>>
+  <$set name="lang" filter="[[$:/language]get[text]get[name]else[en-GB]]" select="0">
+    <!-- Allow lingo-base to have or not have / ending slash, for better dev experience. Then add, e.g. `en-GB/Key` after it. -->
+    <$set name="l10nTarget" filter="[<lingoBaseWithFallback>suffix[/]then<lingoBaseWithFallback>] ~[<lingoBaseWithFallback>addsuffix[/]] +[addsuffix<lang>addsuffix[/]addsuffix<__key__>]" select="0">
+      <$transclude $tiddler=<<l10nTarget>> />
+    </$set>
+  </$set>
+</$set>
+\end

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

@@ -1,12 +1,13 @@
-created: 20150221154907000
-modified: 20150221155706000
-title: lingo Macro
-tags: Macros [[Core Macros]]
 caption: lingo
+created: 20150221154907000
+modified: 20231028123405895
+tags: Macros [[Core Macros]]
+title: lingo Macro
+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/`.
+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 [[t Macro]] instead.
 
 !! Parameters
 

editions/tw5.com/tiddlers/macros/examples/t Macro (Examples).tid

@@ -0,0 +1,14 @@
+created: 20231028120432257
+modified: 20231028122408606
+tags: [[t Macro]] [[Macro Examples]]
+title: t Macro (Examples)
+
+\define lingo-base() t Macro (Examples)
+
+Given the `\define lingo-base() t Macro (Examples)`, this example shows the localizaion key `ExampleKey` being translate to the text in [[t Macro (Examples)/en-GB/ExampleKey]]:
+
+<$macrocall $name=".example" n="1" eg="""<<t ExampleKey>>"""/>
+
+This example shows the `lingo-base` can be set inline as second parameter:
+
+<$macrocall $name=".example" n="2" eg="""<<t ExampleKey "t Macro (Examples)">>"""/>

editions/tw5.com/tiddlers/macros/examples/t Macro (Examples)_en-GB_ExampleKey.tid

@@ -0,0 +1,5 @@
+created: 20231028120526948
+modified: 20231028123420761
+title: t Macro (Examples)/en-GB/ExampleKey
+
+This is the translated text of key "~ExampleKey" under lingo-base `t Macro (Examples)`

editions/tw5.com/tiddlers/macros/t Macro.tid

@@ -0,0 +1,53 @@
+caption: t (translation)
+created: 20231028115714556
+modified: 20231028123219684
+tags: Macros [[Core Macros]]
+title: t Macro
+
+The <<.def t>> [[macro|Macros]] relates to the translation of ~TiddlyWiki's user interface into other languages, just like [[lingo Macro]]. It returns a piece of text in the user's currently selected language. And `t` is the abbreviation of "translation".
+
+The difference to [[lingo Macro]] is that translatable text can be directly placed in user's wiki, instead of in a language plugin.
+
+!! 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 "t">>
+
+!! Example file structure in plugin
+
+When developing a plugin, you may want to organize your i18n (internationalization) files like this on the file system as [[MultiTiddlerFiles]]:
+
+```tree
+├── i18n
+│   ├── en-GB
+│   │   └── Translations.multids
+│   └── zh-Hans
+│       └── Translations.multids
+├── other files
+└── plugin.info
+```
+
+And the content of `i18n/en-GB/Translations.multids` may looks like this:
+
+```multids
+title: $:/plugins/yourName/pluginName/languages/en-GB/
+
+OpenInteractiveCard: Open Interactive Card
+OpenStaticCard: Open Static Card
+```
+
+Later you can use it like:
+
+```tid
+title: someTiddler
+caption: <<t "OpenStaticCard" "$:/plugins/yourName/pluginName/languages/">>
+
+\define lingo-base() $:/plugins/yourName/pluginName/languages/
+\whitespace trim
+
+<<t "OpenInteractiveCard">>
+```