Vite Plugin Pug I18n
A vite plugin with support of rendering multiple pages based on pugjs templates. Plugin also support i18n with proper directory route structure creation.
Installation
npm i -D vite-plugin-pug-i18nPlugin Options
Plugin Options is an object that expect's next properties:
- pages - pages options.
- baseDir - resolved path to pages directory.
- langs - (Optional) language options.
- baseDir - resolved path to langs directory.
- translate - a init function to provide translate function back. As an input this function will receive lang code.
- fallbackLng - i18next fallback language option.
- locals - pug locals.
- options - pug options.
- i18nInitOptions - init options for i18next.
- baseDir - base directory to put all the output files within.
Note: __ and lang are reserved locals. First is translation function that will be provided to pug, second is current language code. This locals are not provided if langs option are null or undefined.
Usage example
You can start with vite javascript template project. And just modify it.
Let's assume you have your pug pages files in src/pages directory of your project:
src/pages/index.pug
src/pages/test-route/test-page.pugWhile language .json files are located in src/language. With 2 language available there - en and fr:
src/language/en.json
src/language/fr.jsonThen you'll need to provide next options to the plugin:
// vite.config.js
import { defineConfig } from 'vite'
import { resolve } from 'path'
import vitePluginPugI18n from 'vite-plugin-pug-i18n'
export default defineConfig({
plugins: [
vitePluginPugI18n({
pages: {
baseDir: resolve(__dirname, 'src/pages')
},
langs: {
baseDir: resolve(__dirname, 'src/language')
}
})
]
})That will generate next static html files structure on build for you in dist:
dist/en/index.html
dist/en/test-route/test-page.html
dist/fr/index.html
dist/fr/test-route/test-page.htmlIn case if langs option will not be provided or will be null, then static html pages will be generated without language support:
dist/index.html
dist/test-route/test-page.htmlRoot redirect to language version
There is no index.html in dist when the language mode is used. You can create it manually in vite's public directory, which will then be copied to dist during build. And add some redirect custom code to it. So it's up to developer which mechanism to use to detect user's language on client side(or server) and auto-redirect to proper url after.
Root index.html example:
<html>
<body>
<script>
window.location="/en";
</script>
</body>
</html>i18next
Plugin is using i18next as a translation function. Language filename must have next format [language-code].json, and the file structure is:
en.json
{
"hello": "Hello!"
}So it is key/value json format. So in pug template you can use it like this:
// index.pug
p #{__('hello')}Javascript files
You can use *.js files in pug that will be processed as vite assets and properly replaced, example:
// index.pug
p #{__('hello')}
script(type='module', src='src/main.js')Where main.js is normal ESMAScript that will be compiled by vite as asset. Within which you can import any sass, scss, css files.
Exposed PUG locals
You still can manually provide locals to pug with or without langs option. But keep in mind that plugin reserved some exposed locals listed here, which can be overriden by your locals.
Default locals exposed to pug:
- base - plugin's baseDir value from configuration.
- prefix - function to prefix properly website URLs.
In a translation mode (when langs option provided) next additional locals exposed to pug:
- i18next - plugin's working instance of i18next in case if it will be required to use it.
- __ - translation function.
- lang - current lang code.
- translation - current language translation json object.
URL Prefix
To prefix assets or any urls on your pages, you can provide vite's base shared configuration option. Exposed prefix function will use it to properly generate urls in pug. Another option is instead of using base, to use plugin's baseDir option. With this option vite will generate and output all the files within the dist + baseDir directory. While exposed prefix function will then properly prefix all the urls according to baseDir value.
Another words prefix function works with both vite's base option and plugin's baseDir.