Skip to contents

Read and Write Translations

Source: R/translator-io.R
translator-io.Rd

Export Translator objects to text files and import such files back into R as Translator objects.

Usage

translator_read(
  path = getOption("transltr.path"),
  encoding = "UTF-8",
  verbose = getOption("transltr.verbose", TRUE),
  translations = TRUE
)

translator_write(
  tr = translator(),
  path = getOption("transltr.path"),
  overwrite = FALSE,
  verbose = getOption("transltr.verbose", TRUE),
  translations = TRUE
)

translations_read(path = "", encoding = "UTF-8", tr = NULL)

translations_write(tr = translator(), path = "", lang = "")

translations_paths(
  tr = translator(),
  parent_dir = dirname(getOption("transltr.path"))
)

Arguments

path

A non-empty and non-NA character string. A path to a file to read from, or write to.

  • This file must be a Translator file for translator_read().

  • This file must be a translations file for translations_read().

See Details for more information. translator_write() automatically creates the parent directories of path (recursively) if they do not exist.

encoding

A non-empty and non-NA character string. The source character encoding. In almost all cases, this should be UTF-8. Other encodings are internally re-encoded to UTF-8 for portability.

verbose

A non-NA logical value. Should progress information be reported?

translations

A non-NA logical value. Should translations files also be read, or written along with path (the Translator file)?

tr

A Translator object.

This argument is NULL by default for translations_read(). If a Translator object is passed to this function, it will read translations and further register them (as long as they correspond to an existing source text).

overwrite

A non-NA logical value. Should existing files be overwritten? If such files are detected and overwrite is set equal to TRUE, an error is thrown.

lang

A non-empty and non-NA character string. The underlying language.

A language is usually a code (of two or three letters) for a native language name. While users retain full control over codes, it is best to use language codes stemming from well-known schemes such as IETF BCP 47, or ISO 639-1 to maximize portability and cross-compatibility.

parent_dir

A non-empty and non-NA character string. A path to a parent directory.

Value

translator_read() returns an R6 object of class Translator.

translator_write() returns NULL, invisibly. It is used for its side-effects of

  • creating a Translator file to the location given by path, and

  • creating further translations file(s) in the same directory if translations is TRUE.

translations_read() returns an S3 object of class ExportedTranslations.

translations_write() returns NULL, invisibly.

translations_paths() returns a named character vector.

Details

The information contained within a Translator object is split: translations are reorganized by language and exported independently from other fields.

translator_write() creates two types of file: a single Translator file, and zero, or more translations files. These are plain text files that can be inspected and modified using a wide variety of tools and systems. They target different audiences:

  • the Translator file is useful to developers, and

  • translations files are meant to be shared with non-technical collaborators such as translators.

translator_read() first reads a Translator file and creates a Translator object from it. It then calls translations_paths() to list expected translations files (that should normally be stored alongside the Translator file), attempts to read them, and registers successfully imported translations.

There are two requirements.

  • All files must be stored in the same directory. By default, this is set equal to inst/transltr/ (see getOption("transltr.path")).

  • Filenames of translations files are standardized and must correspond to languages (language codes, see lang).

The inner workings of the serialization process are thoroughly described in serialize().

Translator file

A Translator file contains a YAML (1.1) representation of a Translator object stripped of all its translations except those that are registered as source text.

Translations files

A translations file contains a FLAT representation of a set of translations sharing the same target language. This format attempts to be as simple as possible for non-technical collaborators.

See also

Translator, serialize()

Examples

# Set source language.
language_source_set("en")

# Create a path to a temporary Translator file.
temp_path <- tempfile(pattern = "translator_", fileext = ".yml")
temp_dir  <- dirname(temp_path)  ## tempdir() could also be used

# Create a Translator object.
# This would normally be done by find_source(), or translator_read().
tr <- translator(
  id = "test-translator",
  en = "English",
  es = "Español",
  fr = "Français",
  text(
    en = "Hello, world!",
    fr = "Bonjour, monde!"),
  text(
    en = "Farewell, world!",
    fr = "Au revoir, monde!"))

# Export it. This creates 3 files: 1 Translator file, and 2 translations
# files because two non-source languages are registered. The file for
# language "es" contains placeholders and must be completed.
translator_write(tr, temp_path)
translator_read(temp_path)

# Translations can be read individually.
translations_files <- translations_paths(tr, temp_dir)
translations_read(translations_files[["es"]])
translations_read(translations_files[["fr"]])

# This is rarely useful, but translations can also be exported individually.
# You may use this to add a new language, as long as it has an entry in the
# underlying Translator object (or file).
tr$set_native_languages(el = "Greek")

translations_files <- translations_paths(tr, temp_dir)

translations_write(tr, translations_files[["el"]], "el")
translations_read(file.path(temp_dir, "el.txt"))