API
The @tolgee/vue
library exports the following components and all available components from @tolgee/web
.
VueTolgee plugin
VueTolgee
plugin attaches Tolgee to a Vue instance. This allows, you to use the $t
function in any Vue component.
import { VueTolgee } from '@tolgee/vue';
...
app.use(VueTolgee, { tolgee });
...
// A child Vue component
<div>
{{ $t('key', 'Default value') }}
</div>
For more refer to the
tolgee.t
function interface.
You can also integrate Tolgee without using the VueTolgee
plugin. In this case use the TolgeeProvider
and the useTranslate
method for translating.
TolgeeProvider
Provides the Tolgee context. Use in root of the application.
import { TolgeeProvider } from '@tolgee/vue';
...
<TolgeeProvider>
<App />
</TolgeeProvider>
Prop fallback?
String | JSX.Element
- rendered when Tolgee is loading translations instead of provided content.
Pass custom loading element when using Vue with JSX.
<TolgeeProvider fallback="Loading...">
<App />
</TolgeeProvider>
Slot fallback?
Alternative for fallback
. Use when you are using Vue with templates:
<TolgeeProvider>
<App />
<template v-slot:fallback>
<div>Loading...</div>
</template>
</TolgeeProvider>
Prop tolgee?
Provide a Tolgee instance. If you use VueTolgee
, this is not necessary.
T
component
Implement translation in your Vue application. It has a very similar API to the t
function.
import { T } from '@tolgee/vue';
<T keyName="..." :params="{ param: '...' }" />
Prop keyName
String
- translation key.
Prop defaultValue?
String
- Rendered if no translation for the specified key (in neither the selected language nor the base language) is present. If not provided, keyName
gets rendered instead.
Prop params?
Record<string, string>
- variable params, which can be used in translation value
(read more about ICU message format).
Prop ns?
string
- translation namespace
Prop noWrap?
Boolean
(default: false
)
false
- in development mode translation will be wrappedtrue
- use when wrapping in dev mode causes problems. In-context translation won't work.
Prop language?
String
- override current Tolgee language. Allows switching to different language for separate translation. Load the language manually with tolgee.loadRecord
.
Children
Feature available from version 5.24.0
Pass children to the T
component that gets mapped to the translation parameters respective to their slot names. Allows implementation of custom components as a part of the translation.
<template>
<T
keyName="translation_with_link"
defaultValue="Click this {link}"
>
<template v-slot:link>
<a href="...">{{ $t('link_label', "link") }}</a>
</template>
</T>
</template>
Composable useTranslate
Use it for loading namespaces for specific components/pages or to get t
function for translating (returned t
function uses first namespace from the list automatically).
function useTranslate(ns?: string | string[]): {
t: Ref<TFnType>;
isLoading: Ref<boolean>;
};
Parameter ns
string
|string[]
- namespace(s) which will be loaded
Property isLoading
(Ref)
boolean
- is true if any of listed namespaces is not loaded yet
Use this property to ensure translations are rendered after they are loaded.
Function t
(Ref)
Returns requested translation and also subscribes component to translation/language changes. Component will be re-rendered every time translation changes. If used with namespaces, t
function will automatically use the first the namespace given to useTranslate
function. Override this with the ns
option.
t('key', 'Default value', <options>);
Check
tolgee.t
function interface.
Composable useTolgee
Returns Tolgee instance as a Ref
. Allows subscription to different events
, which will trigger re-render. Most common usecase is for language switching.
<template>
<div>Language: {{tolgee1.getLanguage()}}</div>
<div>Loading: {{tolgee2.isLoading()}}</div>
</template>
<script setup>
import { useTolgee } from '@tolgee/vue';
// gets updated on language change
const tolgee1 = useTolgee(['language']);
// gets updated when loading changes
const tolgee2 = useTolgee(['loading']);
// never gets updated
const tolgee3 = useTolgee();
</script>