# How to Add Internationalization Support to Custom Plugins in Luban H5

> Add internationalization support to Luban H5 custom plugins. Learn to register keys, map titles, and use $t() in Vue components for global reach.

- Repository: [小小鲁班/luban-h5](https://github.com/ly525/luban-h5)
- Tags: how-to-guide
- Published: 2026-03-06

---

**To add internationalization support to custom plugins in Luban H5, register translation keys in the locale files under `front-end/h5/src/locales/`, add an `i18nTitle` mapping to your plugin definition in `front-end/h5/src/components/plugins/`, and use Vue I18n's `$t()` method inside your Vue components.**

Luban H5 (ly525/luban-h5) is a drag-and-drop H5 page builder that relies on **vue-i18n** for all UI translations. When developing custom plugins for this editor, you must hook into the existing i18n architecture to ensure plugin names, tooltips, and interface elements render correctly across different languages.

## How Luban H5 Handles Internationalization

The editor implements a three-layer internationalization system:

- **Locale Files** – JavaScript objects that map translation keys to strings for each supported language, merged in [`front-end/h5/src/locales/index.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/locales/index.js).
- **Vuex Store** – The `i18n` module at [`front-end/h5/src/store/modules/i18n.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/store/modules/i18n.js) stores the active language code in `state.i18n.lang` and provides the `SetLang` action.
- **Component Mixins** – [`front-end/h5/src/components/core/mixins/i18n.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/components/core/mixins/i18n.js) exposes `currentLang` and translation helpers to any component via Vuex mappings.

When a user switches languages using the header selector ([`front-end/h5/src/components/common/header/LangSelect.vue`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/components/common/header/LangSelect.vue)), the store updates, triggering reactive re-renders of all `$t()` calls and `i18nTitle` lookups.

## Step-by-Step Implementation Guide

### 1. Register Translation Keys in Locale Files

Create a namespace for your plugin in each language file. The editor loads these automatically via [`front-end/h5/src/locales/index.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/locales/index.js).

```js
// front-end/h5/src/locales/zh-CN.js
export default {
  plugin: {
    myCustom: {
      title: '我的自定义插件',
      description: '这是一个示例插件'
    }
  }
}

// front-end/h5/src/locales/en-US.js
export default {
  plugin: {
    myCustom: {
      title: 'My Custom Plugin',
      description: 'A sample plugin'
    }
  }
}

```

### 2. Add i18nTitle to Your Plugin Definition

In your plugin file under `front-end/h5/src/components/plugins/`, add an `i18nTitle` object that maps language codes to localized titles. The editor's left panel ([`front-end/h5/src/components/core/editor/left-panel/shortcuts-panel/index.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/components/core/editor/left-panel/shortcuts-panel/index.js)) renders the name using `plugin.i18nTitle[this.currentLang] || plugin.title`.

```js
// front-end/h5/src/components/plugins/my-custom-plugin.js
export default {
  name: 'my-custom-plugin',
  title: 'My Custom Plugin',  // Fallback for missing translations
  i18nTitle: {
    zh: '我的自定义插件',
    en: 'My Custom Plugin'
  },
  // ... other plugin configuration
}

```

### 3. Use $t() in Your Plugin's Vue Component

For any user-facing text inside your plugin's UI, use the `$t()` helper provided by vue-i18n. This ensures text updates immediately when the language changes.

```vue
<template>
  <div class="my-plugin">
    <h3>{{ $t('plugin.myCustom.title') }}</h3>
    <p>{{ $t('plugin.myCustom.description') }}</p>
    <button @click="handleAction">{{ $t('plugin.myCustom.buttonText') }}</button>
  </div>
</template>

<script>
export default {
  name: 'MyCustomPlugin',
  methods: {
    handleAction() {
      // Custom logic
    }
  }
}
</script>

```

### 4. Access Current Language via Mixins (Optional)

If your plugin needs to perform language-specific logic beyond simple translation, import the `langMixin` to access the active language code directly.

```js
import langMixin from '@/core/mixins/i18n'

export default {
  mixins: [langMixin],
  computed: {
    displayTitle() {
      // Access this.currentLang provided by the mixin
      return this.i18nTitle?.[this.currentLang] || this.title
    }
  }
}

```

## Complete Code Example

Here is a full implementation showing the locale file, plugin definition, and component working together:

**Locale file ([`front-end/h5/src/locales/en-US.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/locales/en-US.js)):**

```js
export default {
  plugin: {
    myButton: {
      title: 'Custom Button',
      tooltip: 'Click to trigger custom behavior'
    }
  }
}

```

**Plugin definition ([`front-end/h5/src/components/plugins/my-button.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/components/plugins/my-button.js)):**

```js
export default {
  name: 'my-button',
  title: 'My Button',
  i18nTitle: {
    zh: '自定义按钮',
    en: 'My Button'
  },
  component: () => import('./my-button-component.vue')
}

```

**Component template ([`my-button-component.vue`](https://github.com/ly525/luban-h5/blob/main/my-button-component.vue)):**

```vue
<template>
  <a-button :title="$t('plugin.myButton.tooltip')" @click="handleClick">
    {{ $t('plugin.myButton.title') }}
  </a-button>
</template>

```

## Key Files in the I18n Architecture

| File | Role |
|------|------|
| [`front-end/h5/src/locales/index.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/locales/index.js) | Bootstraps `VueI18n` and loads all language bundles. |
| [`front-end/h5/src/store/modules/i18n.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/store/modules/i18n.js) | Vuex module storing `state.i18n.lang` and the `SetLang` action. |
| [`front-end/h5/src/components/core/mixins/i18n.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/components/core/mixins/i18n.js) | Provides `currentLang` computed property to components. |
| `front-end/h5/src/components/plugins/**` | Directory for custom plugins; add `i18nTitle` properties here. |
| [`front-end/h5/src/components/core/editor/left-panel/shortcuts-panel/index.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/components/core/editor/left-panel/shortcuts-panel/index.js) | Renders plugin names using `plugin.i18nTitle[this.currentLang]`. |
| [`front-end/h5/src/components/common/header/LangSelect.vue`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/components/common/header/LangSelect.vue) | UI control for switching languages; dispatches `SetLang` to the store. |

## Summary

- **Store translations** in `front-end/h5/src/locales/` using namespaced keys to avoid collisions.
- **Define plugin titles** using the `i18nTitle` object in your plugin definition, allowing the editor to display language-specific names in the plugin list.
- **Render UI text** with `$t()` inside your Vue components to enable reactive language switching.
- **Access language state** via `langMixin` from [`front-end/h5/src/components/core/mixins/i18n.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/components/core/mixins/i18n.js) when you need the current language code for conditional logic.

## Frequently Asked Questions

### What i18n library does Luban H5 use?

Luban H5 uses **vue-i18n** (set up in [`front-end/h5/src/locales/index.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/locales/index.js)) to manage all translations. The library is injected into every component, making the `$t()` method available globally.

### Where should I place translation keys for my custom plugin?

Add keys to the language-specific files in `front-end/h5/src/locales/` (e.g., [`zh-CN.js`](https://github.com/ly525/luban-h5/blob/main/zh-CN.js), [`en-US.js`](https://github.com/ly525/luban-h5/blob/main/en-US.js)). The [`index.js`](https://github.com/ly525/luban-h5/blob/main/index.js) file in that directory automatically merges these objects into the vue-i18n instance, so new keys are immediately available to all components.

### How does the editor decide which plugin title to display?

The shortcuts panel in [`front-end/h5/src/components/core/editor/left-panel/shortcuts-panel/index.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/components/core/editor/left-panel/shortcuts-panel/index.js) checks `plugin.i18nTitle[this.currentLang]` first. If the current language key is missing, it falls back to the generic `plugin.title` property.

### Can I access the current language code inside my plugin component?

Yes. Import `langMixin` from [`front-end/h5/src/components/core/mixins/i18n.js`](https://github.com/ly525/luban-h5/blob/main/front-end/h5/src/components/core/mixins/i18n.js) and include it in your component's `mixins` array. This provides a `currentLang` computed property synced with the Vuex store, allowing you to implement custom logic based on the active language.