Help Center Import/Export
JSON Import - File Structure & Requirements

JSON Import - File Structure & Requirements

Last updated: a month ago
3 minute read
Yuliia Kovalchuk
Developer at SiteTran

ALL ARTICLES

Help Center

JSON File Structure and Requirements for Import

General Requirements

  • File Extension: The file must have a .json or .txt extension.
  • File Format: The file should be a JSON array, with each entry representing a phrase, its translations, and metadata (see example below).

Required Fields

  • source_term: The original phrase in the source language. Each entry must have a source_term, and without it, the file will be rejected.

Optional Fields

  • phrase_id: An optional unique identifier for each phrase.
  • phrase_key: Another optional unique identifier for each phrase.
  • tag_name: Specifies the HTML tag (e.g., div, span) where the phrase appears, providing context in the website's HTML structure.
  • attribute_name: Specifies the HTML attribute (e.g., class, id) where the phrase is located. This can be left as null if not applicable.
  • translations: An object where keys are language codes, and values are the translated terms for each phrase.
  • translation_approved: Tracks whether each translation is approved. Values must be "Y" (approved) or "N" (not approved).
  • translator_email: Object containing translator email addresses by language code.
  • translator_name: Object with translator names by language code.
  • phrase_lang_create_dtime: Object containing timestamps for translation creation, following the ISO 8601 format.
  • translation_flagged: Tracks if the translation is flagged for review, with values "Y" (flagged) or "N" (not flagged).
Important: If translations are included, they must be structured as nested objects. Language codes must follow ISO 639-1 standard, with optional country codes in ISO 3166-1 Alpha-2.

Validation Rules

  • Valid Language Codes: SiteTran accepts language codes in ISO 639-1 format, optionally paired with country codes from ISO 3166-1 Alpha-2 (e.g., fr, es-MX). Invalid codes will trigger a validation error.
  • Matching Language Codes: Any object containing language-specific data must use the same set of language codes as the translations object.
  • Datetime Format: All phrase_lang_create_dtime values must follow ISO 8601. Minor discrepancies such as using date-only formats are accepted (e.g., 2024-09-25 defaults to 2024-09-25T00:00:00.000Z).

Example of Valid JSON File

[
  {
    "phrase_id": 326507,
    "source_term": "Example phrase",
    "tag_name": "div",
    "translations": {
      "fr": "Exemple de phrase",
      "es": "Frase de ejemplo"
    },
    "phrase_lang_create_dtime": {
      "fr": "2024-09-25T10:50:06.000Z",
      "es": "2024-09-25T10:50:03.000Z"
    },
    "translation_flagged": {
      "fr": "Y",
      "es": "N"
    }
  },
  {
    "phrase_id": 326512,
    "source_term": "Example phrase two",
    "tag_name": "div",
    "translations": {
      "fr": "Exemple de phrase deux",
      "es": "Frase de ejemplo dos"
    },
    "phrase_lang_create_dtime": {
      "fr": "2024-09-25T16:01:03.000Z",
      "es": "2024-09-25T16:00:59.000Z"
    },
    "translation_flagged": {
      "fr": "Y",
      "es": "N"
    }
  }
]
Couldn't find what you were looking for?

In this article

Website Translation Made Easy