This plugin consolidates all locale files under the build folder.
gasket create <app-name> --plugins @gasket/plugin-intl
npm i @gasket/plugin-intl
Modify plugins
section of your gasket.config.js
:
module.exports = {
plugins: {
add: [
+ '@gasket/plugin-intl'
]
}
}
-
blacklistModules
- (string[]) list of modules to exclude from bundling. -
localesDir
- (string) change the name of directory to gather translation files from (default:locales
) -
outputDir
- (string) path of directory to build locale and manifest files to (default:./build/locales
) -
assetPrefix
- (string) change the default path to/_locale
endpoint by adding a path prefix here. (default: ''). Used for setting up CDN support for locale files. Thezone
config will be used unlessassetPrefix
is set. -
languageMap
- (object) specify a language mapping here if required (default: {}), e.g.{ 'zh-HK': 'zh-TW', 'zh-SG': 'zh-CN' }
Using this example, if a customer's language is set to
zh-HK
, then the application will load localization data forzh-TW
instead. -
defaultLanguage
- (string) specify a default language to fall back to if none of the fallback language translations are available (default:en-US
)
// gasket.config.js
module.exports = {
intl: {
blacklistModules: ['some-module-with-unwanted-locales'],
}
}
Create a locales
folder in the application root and add a en-US.json file and
start adding localization keys into it.
Create a locales
folder in the application root, create a en-US
folder
under locales
and add files <namespace>.json
with localization keys.
This plugin provides a service worker config that adds Next.js static assets
to precache. This config expects that you will translate the contents of the
en-US
folder into other folders corresponding to the locales of the
translations (e.g. da-DK
).
The service worker should do a sequence of checks to see which translation to use for a given language.
- Exact language match, e.g.
da-DK
to match withda-DK
. - Language match, e.g.
da-XX
to match withda
. - Fallback to US language, e.g.
ar-MA
to fall back toen-US
.
When determining what assets to precache, This plugin defaults to reading the
first language provided in the accept-language
header. However, you can
override this behavior by adding an intlLanguage
hook. The intlLanguage
hook
takes the following parameters:
gasket
- (object) The Gasket configlanguage
- (string) Default language specified by Gasket Intlreq
- (string) The request
It should then return a string indicating the user's language, or null if this
language cannot be found. This plugin will populate intl.language
in the
react state with this value, and use it for future language operations. If null
is returned, Gasket will use en-US
.
module.exports = {
hooks: {
intlLanguage: async function intlLanguageHook(gasket, language, req) {
const { env } = gasket.config;
// Always use en-US in dev for some reason....
if(env === 'dev') return 'en-US';
// This example could be handled via languageMap, but...
if(language.includes('fr')) {
return 'fr-FR';
}
// If no special cases apply, use the default language provided by Gasket.
return language;
}
}
}
When you build your app, the plugin looks for locale
directories in the app
root and in node modules. Each file is then read and output to the build or
outputDir with a hash added to the filename. This hash is based on the contents
of the locale file, so if there are any changes, the file will get a new hash to
ensure it is unique.
Locale files are served with a long cache expiration time. This allows browsers to cache the locale files, and only versions with hash name changes will be newly downloaded.
In order for the app to know the hash name for a particular locale file, a locale manifest is generated at build time. This file should not be cached by the browser, nor should it placed on a CDN during deployments. In most cases, the manifest contents will be served with the first page-render.
To load and utilize locale files on your app, see the @gasket/intl package.