Coconut Snowballs :chestnut: :snowman: :8ball:

What

This system aims to demonstrate how your React components are represented in various language scenarios.

Users can quickly switch between languages and see the results reflected inside your components. They can also leverage the power of the interactive Styleguidist REPEL to customise components and see those changes are represented via real-time translations.

Why

This allows designers, developers and QA to rapidly prototype and stress test components from a localisation perspective.

Usage

The system in split into two main portions, Prepare and Display. The two work together ensuring that we reduce the usage of the AWS Translation API to as little as possible.

Prepare

We pre-render your components default translation references at build time. This acts as a cache to reduce the burden of any real-time translations to only necessary scenarios.

We enrich your Styleguidist build by running the following sequence via our CLI functionality.

Invoke the CLI

The CLI sequence automates the conversion of your Styleguidist Markdown (.md) files into translated .json files. These .json files then act as a cache and are targeted during run time whenever possible to avoid exhausting the real-time AWS Translation API.

• Install the Coconut Snowballs library as a local (or global dependancy).

  npm install --save-dev coconut-snowballs

• If you installed the library locally, create an npm script hook for convenience.

  package.json

  {
    ...
    "scripts": {
      "translate": "coconut-snowballs"
    },
    ...
  }

• Invoke the CLI and supply your Markdown source and Styleguidist asset directories.

  npm run translate -- --markdown="./src" --styleguidist="./assets"

  • Note: If you are running the CLI "locally" make sure to have your AWS access / secret keys setup.

• Tell Styleguidist where to find your cached translation files.

  styleguide.config.js

  module.exports = {
    assetsDir: "./assets"
  };

Example

An example of fetching pre-translated cached json data inside of the Styleguidist documentation.

Real-time translations

If a user customises the content inside the interactive Styleguidist REPEL our cached translations are no longer relevant. In that regard we need to setup an endpoint to to preform real-time transitions.

You can set your endpoint up however you like but we have provided you a module that can handle the translation sequence. In the example below we are using Hapi to create an API along side our json translation sequence.

index.js

const Hapi = require("hapi");
const translate = require("coconut-snowballs/json");
const server = Hapi.server({ host: "localhost", port: 8000 });

server.route({
  method: "POST",
  path: "/translate",
  options: { cors: true },
  handler: ({ payload }) => translate(payload)
});

(async () => {
  try { await server.start(); }
  catch (err) { process.exit(1); }
})();

Example

An example of fetching real-time translated json data inside of the Styleguidist documentation.

Display

To display your component with localisation functionality we need to enrich the Styleguidist documentation with our translation system.

The CLI sequence is dependant on setting up the display scaffold correctly.

• Create a <Translate /> component. This will act as a "hook" for the CLI to use inside the Markdown documentation and handle the async translation sequences ("get cached" and "make new").

  Translate.js

  import React, { Component } from "react";
  import CoconutSnowballs from "coconut-snowballs";
  import axios from "axios";
    
  export default class Translate extends Component {
    getCachedData = async id => {
      // Get cahced translation data from the ./asset directory.
      const response = await axios.get(`/translations/${id}.json`);
      return response.data;
    };
    
    makeNewTranslation = async (language, english) => {
      // Supply our Hapi API with JSON and recieve new translation data .
      const json = JSON.stringify(english);
      const response = await axios.post(`http://my-translate-endpoint/translate`, { language, json });
      return response.data;
    };
    
    render() {
      const { props, getCachedData, makeNewTranslation } = this;
      return (
        <CoconutSnowballs {...props}
          getCachedData={getCachedData}
          makeNewTranslation={makeNewTranslation}
        />
      );
    }
  }

• Enrich your component(s) with the <Translate /> component. The component expects three props which are used to create cached and new translations as easily as possible:

  • id: The id reference the cached json data will be saved and fetched under.
  • languages: An array of language code(s) that the current component supports.
  • english: An object containing the string references that translations will be based on.

  Note: The component must be called <Translate /> in your Markdown examples

  Button.md

  const Translate = require("./Translate").default;
  <Translate
    id="1a2b3c"
    languages={["ar", "zh", "fr", "de", "pt", "es"]}
    english={{ primary: "Update", success: "Accept", danger: "Delete" }}>
    {t => [
      <Button version="primary">{t.primary}</Button>,
      <Button version="success">{t.success}</Button>,
      <Button version="danger">{t.danger}</Button>
    ]}
  </Translate>;

License

MIT