fulcro.i18n — fulcrologic/fulcro 2.6.0-RC6

Internationalization support GNU gettext-style.

This support allows translations to stay in raw gettext PO file format, and be served as normal API data loads.

To use this support:

1. Use tr, trf, trc, etc. to embed messages in your UI.
2. Embed a locale selector, such as the one provided.
3. Configure your server to serve locales.
4. Compile the source of your application with whitespace optimizations.
5. Use xgettext (GNU CLI utility) to extract the strings from the js output of (4). xgettext --from-code=UTF-8 --debug -k -ktr_alpha:1 -ktrc_alpha:1c,2 -ktrf_alpha:1 -o messages.pot application.js
6. Have translators generate PO files for each locale you desire, and place those where your server can serve them.

See the Developer's Guide for more details.

ensure-locale-loaded! clj/s

(ensure-locale-loaded! reconciler locale)

Ensure that the given locale is loaded. Is a no-op if there are translations in app state for the given locale which is a keyword like :es-MX.

is-locale-loaded? clj/s

(is-locale-loaded? state-map locale)

Returns true if the given locale is loaded in the given state map.

load-locale clj

(load-locale po-dir locale)

Load a po file. If po-dir is relative then it will come from CLASSPATH. If it is absolute it wil; come from the filesystem. The locale must be a keyword that matches an existing locale name in ll-CC format (e.g. :en-US).

Returns a map keyed by locale keyword (e.g. :en-US) whose value is the correct data for client-side translations.

Locale clj/s≠

clj

cljs

(Locale)

LocaleSelector clj/s≠

clj

cljs

(LocaleSelector)

t clj/s

(t string)

(t string {:keys [:fulcro.i18n/context] :as options})

Translate a string in the context of the given component.

This is a general-purpose function for doing everything that tr, trc, and trf do; however, it does not allow for source-level string extraction with GNU gettext. It is recommended that you use use tr, trc, and such instead.

Options is sent to the configured formatter, and may also include ::i18n/context to represent translation context.

tr clj/s macro

(tr msg)

Translate the given literal string. The argument MUST be a literal string so that it can be properly extracted for use in gettext message files as the message key. This macro throws a detailed assertion error if you violate this restriction. See trf for generating translations that require formatting (e.g. construction from variables).

tr-ssr clj

(tr-ssr msg)

tr-unsafe clj/s macro

(tr-unsafe msg)

Look up the given message. Using this function without a literal string will make string extraction from source impossible. This means you have to use some other mechanism to make sure the string ends up in translation files (such as manually calling tr on the various raw string values elsewhere in your program).

trc clj/s macro

(trc context msg)

Same as tr, but include a context message to the translator. This is recommended when asking for a translation to something vague.

For example:

   (tr "M")

is the same as asking a translator to translate the letter 'M'.

Using:

   (trc "abbreviation for male gender" "M")

lets the translator know what you want. Of course, the msg key is the default language value (US English)

trc-ssr clj

(trc-ssr ctxt msg)

trc-unsafe clj/s macro

(trc-unsafe context msg)

Same as trc, but does not check for literal strings for arguments. THIS MEANS strings extraction from source for these values will not be possible, and you will have to manually ensure they are included in translations.

trf clj/s macro

(trf format & args)

Translate a format string, then use it to format a message with the given arguments. The format MUST be a literal string for extraction by gettext. The arguments should a map of keyword/value pairs that will match the embedded items to format.

(trf "{name} owes {amount, currency)" {:name who :amount amt})

trf-ssr clj

(trf-ssr fmt & rawargs)

ui-locale-selector clj/s

with-locale clj/s macro

(with-locale message-formatter locale & render-body)

Establish a message formatting and locale context for rendering. Can be used on the client or server to force a given locale and message formatting context for the enclosed elements.

It is typically used for server-side rendering like this:

(defn message-formatter ...) ; a server-side message formatter, like IBM's ICU library

(defn generate-index-html [state-db app-html]
  (let [initial-state-script (ssr/initial-state->script-tag state-db)]
    (str "<html><head>" initial-state-script "</head><body><div id='app'>" app-html "</div></body></html>")))

(let [initial-tree     (prim/get-initial-state Root {})
      es-locale        (i18n/load-locale "my-po-files" :es)
      tree-with-locale (assoc initial-tree ::i18n/current-locale es-locale)
      initial-db       (ssr/build-initial-state tree-with-locale Root) ; embed this as initial state in the HTML
      ui-root          (prim/factory Root)]
  (generate-index-html initial-db  ; some function that generates the complete wrapped HTML. See server-side rendering for more detail
    (i18n/with-locale message-formatter es-locale
      (dom/render-to-str (ui-root tree-with-locale)))))

Note: locale can technically contain anything that the given UI needs in shared props, since this macro will completely override shared props with the given information.