-
Notifications
You must be signed in to change notification settings - Fork 1.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat: t macro and docs #7821
Merged
Merged
feat: t macro and docs #7821
Changes from 17 commits
Commits
Show all changes
20 commits
Select commit
Hold shift + click to select a range
a6b6132
feat: t macro and docs
linonetwo cacd236
feat: support block mode so you can transclude whole tiddler
linonetwo 7d321fe
refactor: use lingo and procedure
linonetwo 2055f36
refactor: use function instead of set variable
linonetwo a8c5bc0
docs: about mode:"inline"
linonetwo 9fbd71e
Update LingoMacro.tid
linonetwo bef871d
docs: more usage about inline
linonetwo 36a9d49
refactor: update translate macro to reuse lingo macro
linonetwo aaf3182
Delete translateMacro.tid
linonetwo f3eefa6
refactor: update translation of tiddlyweb
linonetwo ab9572e
docs: more tiddlyweb l10n
linonetwo 810b5d5
feat: add comment, so when use <$text text=<<lingo>> by mistake, it s…
linonetwo 2579d7f
i18n: add more l10n
linonetwo 33456a5
feat: add tree to plugin to reveal l10n structure
linonetwo 8840a57
i18n: add menubar translation for example
linonetwo 7f2b8b2
i18n: more for menubal
linonetwo 6603794
docs: Headings -> Heading
linonetwo 5c8b392
Merge remote-tracking branch 'upstream/master' into feat/i18n
linonetwo fb70f0b
refactor: remove the "tree" tid
linonetwo 14f7f98
Revert "refactor: remove the "tree" tid"
linonetwo File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,10 +1,24 @@ | ||
| 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 lingo(title,override-lingo-base) | ||
| <!-- Lingo procedure --> | ||
| <!-- 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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,16 +1,37 @@ | ||
| caption: lingo | ||
| created: 20150221154907000 | ||
| modified: 20150221155706000 | ||
| title: lingo Macro | ||
| modified: 20231028123405895 | ||
| tags: Macros [[Core Macros]] | ||
| caption: lingo | ||
| 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 | ||
| # Any l10n (localization) strings outside of the language plugins | ||
|
|
||
| !! Language plugins | ||
|
|
||
| !! Parameters | ||
| 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)}} |
21 changes: 21 additions & 0 deletions
21
editions/tw5.com/tiddlers/macros/examples/lingo Macro (custom base examples).tid
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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>>"""/> |
8 changes: 8 additions & 0 deletions
8
.../tw5.com/tiddlers/macros/examples/lingo Macro (custom base examples)_en-GB_ExampleKey.tid
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| created: 20231028120526948 | ||
| 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 `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.) |
73 changes: 73 additions & 0 deletions
73
editions/tw5.com/tiddlers/macros/examples/lingo Macro (file structure).tid
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,73 @@ | ||
| 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 | ||
| ``` | ||
|
|
||
| See [[$:/plugins/tiddlywiki/menubar/tree]] for an example. | ||
|
|
||
| !!! 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. |
2 changes: 1 addition & 1 deletion
2
...w5.com/tiddlers/macros/examples/lingo.tid → ...ingo Macro (language plugin examples).tid
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
25 changes: 25 additions & 0 deletions
25
plugins/tiddlywiki/menubar/language/en-GB/Translations.multids
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| title: $:/plugins/tiddlywiki/menubar/language/en-GB/ | ||
|
|
||
| Config/Heading1: Menu Bar Configuration | ||
| Config/MenuItems/Heading: Menu Items | ||
| Config/MenuItems/Description: Select which menu items will be shown. You can also drag items to reorder them. | ||
| Config/BreakpointPosition/Heading: Breakpoint Position | ||
| Config/BreakpointPosition/Description: The breakpoint position between narrow and wide screens. Should include CSS units (eg. `400px`). | ||
| Config/ContentsTag/Heading: Contents Tag | ||
| Config/ContentsTag/Description: The tag for the ~TableOfContents used in the Contents dropdown | ||
| Config/MenuBarColours/Heading: Menu Bar Colours | ||
| Config/MenuBarColours/Description: To change the colour of the menu bar, define the colours `menubar-foreground` and `menubar-background` in the currently selected palette | ||
| Items/TOC/Name: Contents | ||
| Items/TOC/Description: Table of Contents | ||
| Items/Hamburger/Name: Hamburger | ||
| Items/Hamburger/Description: Show the full menu bar on a narrow screen | ||
| Items/PageControls/Name: Page controls | ||
| Items/PageControls/Description: Page controls from the sidebar | ||
| Items/Search/Name: Search | ||
| Items/Server/Name: Server | ||
| Items/Server/Description: Server options | ||
| Items/Sidebar/Name: Sidebar | ||
| Items/TopLeftBar/Name: Legacy Top Left Bar | ||
| Items/TopLeftBar/Description: Items from $:/tags/TopLeftBar | ||
| Items/TopRightBar/Name: Legacy Top Right Bar | ||
| Items/TopRightBar/Description: Items from $:/tags/TopRightBar |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,30 @@ | ||
| title: $:/plugins/tiddlywiki/menubar/language/en-GB/readme | ||
|
|
||
| !! Introduction | ||
|
|
||
| This plugin provides a menu bar with the following features: | ||
|
|
||
| * Menu items take the form of simple text links, dropdowns, or entirely custom content | ||
| * Menu items can be individually enabled via the control panel | ||
| * Responds to reduced screen width by abbreviating the menu items to a "hamburger" dropdown | ||
|
|
||
| !! Menu Item Tiddlers | ||
|
|
||
| Menu items are tagged <<tag $:/tags/MenuBar>>. The following fields are used by this plugin: | ||
|
|
||
| |!Field Name |!Purpose | | ||
| |title |Each menu item must have a unique title (not shown to the user) | | ||
| |description |Description for use in listings | | ||
| |tags |Must contain `$:/tags/MenuBar` | | ||
| |caption |The text that is displayed for the menu item. Avoid links, using `~` to suppress CamelCase links if required | | ||
| |target |For simple link menu items specifies a tiddler title as the target of the link | | ||
| |is-dropdown |Set to `yes` to indicate a dropdown menu item | | ||
| |dropdown-position |Optional position for the dropdown (can be ''left'', ''above'', ''aboveleft'', ''aboveright'', ''right'', ''belowleft'', ''belowright'' or ''below'') | | ||
| |text |For dropdown menu items, specifies the body of the dropdown | | ||
| |custom-menu-content |Optional wikitext to be displayed in place of the caption | | ||
| |custom-menu-styles-wide |Optional string of styles to be applied to menu item when the menubar is wide | | ||
| |custom-menu-styles-narrow |Optional string of styles to be applied to menu item when the menubar is narrow | | ||
|
|
||
| Custom menu items should make sure that the clickable link or button is an immediate child, and not wrapped in another element. | ||
|
|
||
| Note that menu items can be pushed to the right of the menu bar setting the ''custom-menu-styles'' field to `float: right;`. |
25 changes: 25 additions & 0 deletions
25
plugins/tiddlywiki/menubar/language/zh-Hans/Translations.multids
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| title: $:/plugins/tiddlywiki/menubar/language/zh-Hans/ | ||
|
|
||
| Config/Heading1: 菜单栏配置 | ||
| Config/MenuItems/Heading: 菜单项 | ||
| Config/MenuItems/Description: 选择要显示的菜单项。您还可以通过拖动项目来重新排序。 | ||
| Config/BreakpointPosition/Heading: 响应式断点位置 | ||
| Config/BreakpointPosition/Description: 窄屏和宽屏之间的分界点位置。应包含 CSS 单位（如 `400px`）。 | ||
| Config/ContentsTag/Heading: 内容标签 | ||
| Config/ContentsTag/Description: 内容下拉菜单中使用的 TOC 目录标签 | ||
| Config/MenuBarColours/Heading: 菜单栏颜色 | ||
| Config/MenuBarColours/Description: 要更改菜单栏的颜色，请在当前选定的调色板中定义颜色 `menubar-foreground` 和 `menubar-background`。 | ||
| Items/TOC/Name: 内容 | ||
| Items/TOC/Description: 目录 | ||
| Items/Hamburger/Name: 抽屉 | ||
| Items/Hamburger/Description: 在窄屏幕上显示完整的菜单栏 | ||
| Items/PageControls/Name: 页面控件 | ||
| Items/PageControls/Description: 来自侧边栏的页面控件 | ||
| Items/Search/Name: 搜索 | ||
| Items/Server/Name: 服务器 | ||
| Items/Server/Description: 服务器选项 | ||
| Items/Sidebar/Name: 侧边栏 | ||
| Items/TopLeftBar/Name: 旧版左上角栏 | ||
| Items/TopLeftBar/Description: 来自 $:/tags/TopLeftBar 的项目 | ||
| Items/TopRightBar/Name: 旧版右上角栏 | ||
| Items/TopRightBar/Description: 来自 $:/tags/TopRightBar 的项目 | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@linonetwo .. It seems the translations are part of the plugin here. That's not what users want. I personally do not want to carry 32 translations with every core plugin, since I do only need 2 or 3 at most.
As a user I do expect them to be added individually
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We can move them to a new sub-plugin, like codemirror's, and sub-plugin add tiddlers to parent plugin's path.
I can move zh-Hans translations to a sub-plugin, only leave en-GB here.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is not that big. If this is not very necessary, I can leave it to next PR. I may be busy on https://github.com/tiddly-gittly/TidGi-Mobile these days.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@pmario while I understand your position on this, I do not think that it is the way that we should go.
The architecture developed here will work with translations that are integral or are packaged as a separate plugin. For the core plugins, I do not think it is acceptable to expose a separate plugin for each translation of the menu bar. I think there are two viable options:
The key point here is that the usability of keeping translations together absolutely trumps any phantom concerns about saving a few hundred bytes.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It's not a view hundred bytes.
menubar has about 1400Byte of text x 32 languages atm is about 45kByte of language related text.
The plugin itself is exported as JSON has 25kByte. So the plugin-size will be almost tripled.
Since the goal may be to have more translations, it will be worse.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@pmario I think Jeremy means if it is big enough, we can still move them out, but not placed in sub-plugin -- place them in core language plugin instead -- for core plugins. I can try this later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I do not see that as a problem. It's very hard to put together a plausible argument that that extra 25KB has any meaningful impact on anything. We have to make things easier for the majority, and not burden all users with an additional cognitive burden for the benefit of a small group.