@abradley2/elm-i18next-gen

Elm I18Next Code Generation

An elm-codegen library for creating type-safe helper methods for the excellent ChristophP/elm-i18next package.

If you have a large Elm application in a business setting, you should strongly consider supporting internationalization even if you aren't considering adding extra languages to your app. Your project manager who would much rather change a line in a JSON file than put another 1-point ticket into your sprint will thank you for it.

CLI Usage (Recommended)

Use the cli via npx @abradley2/elm-i18next-gen -- --flags-from="path/to/translations.en.json" to generate the code for your translations.

This simply proxies to elm-codegen without having to add a codegen directory to your current project.

Elm Codegen Usage

• Follow the "Getting Started" guide from elm-codegen
• In your initialized codegen project, elm install abradley2/elm-i18next-gen

import I18Next.Gen
import Gen.CodeGen.Generate as Generate
import Json.Decode exposing (Value)

main : Platform Value () ()
main = 
    Generate.fromJson
        I18NextGen.flagsDecoder
        I18NextGen.files

Consuming the module in this way allows you to have different code generation paths depending on dynamic flags. But if you're only generating code for translations, the above is sufficient.

Then just run elm-codegen, supplying the translations file as flags.

npx elm-codegen run --flags-from="path/to/translations/en.json"

Example

You should have a root directory that contains your Elm application. From this directory you've called npx elm-codegen init and have something resembling the following:

elm-app/
|--assets/
|  |--translations.en.json
|--src/
|  |--Main.elm
|--codegen/
   |--Generate.elm

When you have followed the steps in the Usage section, running-

npx elm-codegen run --flags-from="assets/translations.en.json"

-from your elm-app root should produce:

elm-app/
|--assets/
|  |--translations.en.json
|--src/
|  |--Main.elm
|--codegen/
|  |--Generate.elm
|--generated/
   |--Language.elm
   |--Translations.elm
   |--Translations/   

A translations file like this, conforming to the I18Next V2 specification:

{
   "general greeting": "Hello there",
   "personal greeting": "Hello {{name}}"
}

-will generate:

generalGreeting : List I18Next.Translations -> String
generalGreeting translations =
    I18Next.tf translations "generalGreeting"


personalGreeting : List I18Next.Translations -> { name : String } -> String
personalGreeting translations replacements =
    I18Next.trf
        translations
        I18Next.Curly
        "personalGreeting"
        [ ( "name", replacements.name ) ]

-and a default implementation of I18Next.Translations in the sibling Language.elm module.

defaultLanguage : I18Next.Translations
defaultLanguage =
    I18Next.fromTree
         [ ( ""
           , I18Next.object
                [ ( "generalGreeting", I18Next.string "Hello there" ) 
                , ( "personalGreeting", I18Next.string "Hello {{name}}" )
                ]
           )
         ]

You can also nest translations by page as the I18Next V2 specification allows.

{
   "home": { ... },
   "login": { ... }
}

This will create sub-modules in the Translations directory.

Recommended Pattern

It is recommended that you only run this codegen for a single default language. Part of the output includes a defaultLanguage export of the I18Next.Translations type. For all your translations that are not part of your default language, use I18Next.translationsDecoder as you normally would.

Thanks

This library is largely based upon the work done by Yoni Gibbs on elm-i8next-gen