TiddlyWiki5/editions/tw5.com/tiddlers/macros/translateMacro.tid

caption: translate
created: 20231028115714556
modified: 20231216122319684
tags: Macros [[Core Macros]]
title: translate Macro

The <<.def translate>> [[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
;mode
: Optional parameter like the "mode" parameter in [[TranscludeWidget]], default to "block". If you are using translation in a title, you can add `mode:"inline"` to it.

<<.macro-examples "translate">>

!! Example file structure in plugin

!!! 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: <<translate "OpenStaticCard" "$:/plugins/yourName/pluginName/language/">>

\define lingo-base() $:/plugins/yourName/pluginName/language/
\whitespace trim

<<translate "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/

!! <<translate "OpenInteractiveCard" mode:"inline">>

<<translate "SomeLongText">>
```