Yatapp

Welcome to Yata integration Hex package, this package will allow you to easy get your translations from https://www.yatapp.net service.

Installation

Add yatapp to your list of dependencies and to applications in mix.exs:

# mix.exs

def deps do
  [
    {:yatapp, "~> 0.3.0"}
  ]
end

def application do
  [applications: [:yatapp]]
end

Configuration

Package can be used in two ways:

integration through API
websocket integration

API Integration

Add configuration to your config/config.exs:

# config.exs

config :yatapp,
  api_key: System.get_env("YATA_API_KEY"),
  project_id: System.get_env("YATA_PROJECT_ID"),
  locales: ~w(en),
  translations_format: "yml",
  save_to_path: "priv/locales/",
  root: false,
  strip_empty: false,
  enable_websocket: false,
  download_on_start: true

API integration allows you to download all translation using mix task:

$ mix yatapp.download_translations

Websocket Integration

Add configuration to your config/config.exs:

# config.exs

config :yatapp,
  api_key: System.get_env("YATA_API_KEY"),
  project_id: System.get_env("YATA_PROJECT_ID"),
  default_locale: "en",
  locales: ~w(en),
  otp_app: :my_app,
  json_parser: Jason,
  store: Yatapp.Store.ETS,
  download_on_start: true,
  save_to_path: "priv/locales/",
  translations_format: "json",
  translation_file_parser: Jason,
  root: false,
  strip_empty: false,
  enable_websocket: true,
  var_prefix: "%{",
  var_suffix: "}",
  fallback: false

Websocket integration connects to Yata server and stays open. All changes in translations are auto-fetched to the app.

When app connects to the Yata server for the first time it fetches all translation and saves them to the ETS table when download_on_start option is set to true. If not it will fetch translations to the ETS table from files. Then all actions on translations like create, update and delete are broadcasting information and the ETS table is updated.

The values for given locale and key can be fetched using Yatappp.ExI18n module:

# Examples

# en
number: 1
hello_name: "Hello %{name}"

Yatapp.translate("en", "number") #=> 1
Yatapp.translate("en", "hello_name", %{name: "John"}) #=> "Hello John"

Download translation

There are two options to download translations. First, by using mix task:

$ mix yatapp.download_translations

Mix task saves downloaded translations files to the indicated directory in the configuration.

Whenever an application starts, we fetch new translations from Yata. The download_on_start option, which is set to true by default, is responsible for this behavior. If you prefer to fetch translations from local files on start, set download_on_start to false.

Pluralization

Yata Pluralization is useful when you want your application to customize pluralization rules. The base pluralizer is Yatapp.Pluralization.Base which apply rules with three keys: :zero, :one and :other. You can create your own and set it as your default pluralizer (see Yatapp.Pluralization.Example). To set new pluralizer change configuration settings:

# config.exs

config :yatapp,
  pluralizer: Yatapp.Pluralization.Example

The interpolation value :count has a special role it both is interpolated to the translation and used to pick a pluralization form the translations according to the pluralization rules defined in the pluralization backend.

# Examples

# en

messages:
  zero: "no message"
  one: "1 message"
  other: "%{count} messages"

Yatapp.translate("en", "messages", %{count: 0}) #=> "no message"
Yatapp.translate("en", "messages", %{count: 1}) #=> "1 message"
Yatapp.translate("en", "messages", %{count: 2}) #=> "no messages"

Language Plural Rules (CLDR)

Configure http timeouts

Http timeout options:

:timeout - timeout for establishing a TCP or SSL connection, in milliseconds. Default is 8000
:recv_timeout - timeout for receiving an HTTP response from the socket. Default is 5000

# config.exs

config :yatapp,
  http: %{
    timeout: 50_000,
    recv_timeout: 50_000
  }

Store

You can choose where you want to store your translations. The default store is the Yata.Store.ETS table. The other store you can set is Yatapp.Store.PersistentTerm or write your own module.

Parsers

There're two parsers json_parser and translation_file_parser. json_parser is used to parse the response from API for json files used to fetch translations through Websocket. The second one is translation_file_parser which is used to parse downloaded files. Both are set to Json parser by default.

Configuration Parameters

Option	Description	Default	Websocket	API
api_key	Organization Settings > Security > API token		required	required
project_id	Organization Settings > Security > Projects > Id		required	required
default_locale	Default locale in your application.	`"en"`	optional	-
locales	Supported locales.	`["en"]`	optional	optional
otp_app	Used to generate proper path to locale files		-	-
store	Module that implements `Yatapp.Store`	`Yatapp.Store.ETS`	-	-
download_on_start	Download all translations when app starts	`true`	-	-
json_parser	JSON parser that will be used to parse response from API	`Jason`	-	required
fallback	Fallback to default locale if translation empty.	`false`	optional	-
translations_format	Format you wish to get files in, available for now are (yml, js, json, properties, xml, xml_escaped, xml_android_resource, strings, plist)	`"yml"`	-	optional
translation_file_parser	Parser that will parse downloaded files		-	optional
save_to_path	A directory where translations will be saved.	`"priv/locales/"`	-	optional
root	Download with language as a root element of the translation	`false`	-	optional
strip_empty	Generate only keys that have text and skip empty ones	`false`	-	optional
enable_websocket	Enable websocket integration	`false`	required	optional
var_prefix	Prefix to values in translations.	`%{`	optional	optional
var_suffix	Suffix for values in translations.	`}`	optional	optional
pluralizer	Pluralizer that will be used to parse plural forms	`Yatapp.Pluralization.Base`	-	-
http	Set HTTPoison timeouts: `timeout` and `recv_timeout`	`8000 and 5000 miliseconds`	optional	optional

← Previous Page API Reference