About

This app allows you to import and export proprietary or uncommon (single-language) file formats into Crowdin. It ensures that your file's structure, metadata and contextual information are preserved throughout the translation process.

Check the Crowdin Store for the custom file format app if you need to translate a multilingual file.

Configuration Requirements

The app needs to be configured before use; otherwise, it won’t be able to process files. Please use it only in projects where a custom format is truly required. When enabled, the app won’t support other file formats in the project. Be cautious when selecting projects for its activation.

Key Features

• Import/Export Custom Formats: Directly handle your unique file formats within Crowdin, with no need for manual conversion.
• Preserve File Structure: Maintain your file’s original structure, including comments and metadata, to ensure context is available for translators.
• User-Defined Parsing: Define how your files are parsed and reconstructed, allowing Crowdin to support virtually any file format.

Custom code

To use this app, you will need to provide two code snippets: one for importing your file format into Crowdin and another for exporting translations back into the original format. You can use this GPT to generate the necessary code, tailored specifically to your file format. If you need assistance, the Crowdin Support team is available to help you create these code snippets, ensuring a smooth integration process.

Screenshot

Sample import code

This is the importer and exporter for a JSON file like the following:

{
  "appName": {
    "message": "string 1",
    "description": "context_1"
  },
  "extName": {
    "message": "string 2",
    "description": "context_2"
  },
  "extDesc": {
    "message": "string 3",
    "description": "context_3"
  }
}

// Importer Code
const contentObj = JSON.parse(content);

for (const key in contentObj) {
  const item = contentObj[key];
  const stringObj = {
    identifier: key,
    text: item.message,
    context: item.description || null,  // Optional: Only include context if it's provided
  };

  // If importing translations
  if (targetLanguages.length > 0) {
    stringObj.translations = {};
    for (const lang of targetLanguages) {
      stringObj.translations[lang.id] = {
        text: item.message, // Assuming that the source text is the same as the translated text if not translated
        status: "untranslated" // Default status
      };
    }
  }

  strings.push(stringObj);
}

Sample export code

// Exporter Code
const translatedContent = JSON.parse(content);

for (const stringObj of strings) {
  if (translatedContent[stringObj.identifier]) {
    translatedContent[stringObj.identifier].message = stringObj.text;

    // If exporting translations
    if (stringObj.translations) {
      for (const lang in stringObj.translations) {
        if (stringObj.translations[lang] && stringObj.translations[lang].text) {
          translatedContent[stringObj.identifier].message = stringObj.translations[lang].text;
        }
      }
    }
  }
}

// Overwrite content with the translated content
content = JSON.stringify(translatedContent, null, 2);

Guide for Developing Custom File Format Code for Crowdin

1. Importer Code: Transforms the source file into an array of Crowdin string objects.
2. Exporter Code: Converts an array of Crowdin string objects back into a file that can be consumed by the user, including translations.

Writing the Importer Code

Your importer code should convert the file content into an array of Crowdin string objects. Here’s an example structure:

[
  {
    "identifier": "string-key-1",
    "context": "Some context", // optional
    "maxLength": 10, // optional, default null
    "isHidden": false, // optional, default null
    "labels": ["label-one", "label-two"], // optional, default []
    "text": "String source text", // required
    "translations": {
      "uk": {
        "text": "Переклад стрічки", // required
        "status": "untranslated | translated | approved" // optional, default "translated"
      }
    }
  }
]

Environment Variables Available in Import Code

• strings: A global variable, an empty array where your code should populate Crowdin string objects.
• content: Contains the source file content in UTF-8 encoding.
• error: Set this variable to a string if your code encounters an error and cannot form the strings array.
• fileName: The name of the source file (e.g., 'source-file.json').
• filePath: The file path within the Crowdin project (e.g., '/main/source-file.json').
• fileId: The unique ID for the file in Crowdin.
• targetLanguages: An array of objects containing details about each target language.

Writing the Exporter Code

The exporter code should convert Crowdin string objects back into the original file format, with translations included. You will need to:

• Read the source file content from the content variable.
• Update the content variable with the new translated content before the code exits.