translator_read {transltr}R Documentation

Read and Write Translations

Description

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.

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.

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:

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.

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.

Value

translator_read() returns an R6 object of class Translator.

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

translations_read() returns an S3 object of class ExportedTranslations.

translations_write() returns NULL, invisibly.

translations_paths() returns a named character vector.

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"))


[Package transltr version 0.1.0 Index]