Skip to content

BKWLD/cloak-i18n

Repository files navigation

@cloak-app/i18n

Localization conventions for Cloak + Craft.

Install

  1. Install with yarn add @cloak-app/i18n
  2. Add to nuxt.config with modules: ['@cloak-app/i18n']
  3. Install and configure a Cloak CMS package, like @cloak-app/craft.
    • CMS packages must be added after the @cloak-app/i18n module in modules so that their injected clients are available to the fetch-translations.coffee plugin.
    • Currently only @cloak-app/craft is supported
  4. Add this.$nuxtI18nHead({ addSeoAttributes:true }) to your head, probably in your default layout, as described in the @nuxtjs/i18n docs

If using the generateJson option, you'll need to support CORS requests for the JSON files. If using Netlify, add this to your static/_redirects file:

# Allow access to i18n json files
/i18n/*
	Access-Control-Allow-Origin: *

Module Options

Set these properties within cloak: { i18n: { ... } } in the nuxt.config:

  • currentCode - The code code (see the locales object) of the current locale. Defaults to process.env.LOCALE_CODE and then process.env.CMS_SITE (which converts _ to - to convert Craft handle to ISO code). See the @nuxtjs/i18n defaultLocale option.
  • locales - An array of objects for defining the list of supported locales. This array is similar to the @nuxtjs/i18n locales option. The objects look like:
    {
      code: 'en', // Should be an ISO code
      domain: 'https://cloak-i18n.netlify.app', // Should be full origin
    
      // @cloak-app/i18n additions
      currency: 'USD', // Optional, used with $n()
    }
  • generateJson - Boolean to enable static generation of JSON files for each locale's static strings. You would enable this if you wanted to use the static strings outside of Nuxt, like as part of components that are used in a Shopify theme. The JSON is written to /dist/i18n/{code}.json where {code} comes from the locales array.
  • craft.categories - An array of category titles from Translations Admin. If undefined, it's treated as ["site"] by Translations Admin.

Project Dependencies

  • This package expects that there is a unique Netlify Site for every locale. In other words, when you switch locales, you are switching domains.
  • If using Craft, you're expected to use the Translations Admin plugin fror static translations.

Usage

Static Strings

This package uses @nuxtjs/i18n which, itself, consumes vue-i18n. Thus, look to their docs for a deeper explanantion for how to translate text. The most common helper you'll use is $t(). For example:

<button>{{ $t('articles.read_me') }}</button>

Components

<cloak-i18n-locale-selector />

Renders a select-style menu for choosing a locale. This component can be configured with the following Stylus or CSS customer properties:

  • cloak-i18n-locale-selector-radius - The radius of the select button and the menu background.
  • cloak-i18n-locale-selector-padding-h - The horizontal padding within the toggle button and in the select menu.
  • cloak-i18n-locale-selector-toggle-height - The height of the select button.
  • cloak-i18n-locale-selector-options-padding-v - The vertical padding within the select menu and the spacing between locale options within the menu.

Contributing

Run yarn dev to open a Nuxt dev build of the demo directory.