How to Add Internationalization Support to Custom Plugins in Luban H5

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.
• Vuex Store – The i18n module at 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 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), 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.

// 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) renders the name using plugin.i18nTitle[this.currentLang] || plugin.title.

// 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.

<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.

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):

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

Plugin definition (front-end/h5/src/components/plugins/my-button.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):

<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	Bootstraps VueI18n and loads all language bundles.
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	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	Renders plugin names using plugin.i18nTitle[this.currentLang].
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 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) 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, en-US.js). The 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}