The Translate plugin for Flatfile integrates with the Google Translate API to automatically translate the text content of specified fields within a sheet. When records are processed, the plugin takes the values from designated source fields, translates them from a specified source language to a target language, and then adds the translated text into newly created fields. The new fields are automatically named by appending the target language code to the original field name (e.g., ‘description’ becomes ‘description_es’). This is useful for data localization, preparing multilingual product catalogs, or standardizing user-submitted content into a single language.

​
Installation

Install the plugin using npm:

npm install @flatfile/plugin-convert-translate

​
Configuration & Parameters

The plugin requires a configuration object with the following properties. All options are required and there are no default values:

ParameterTypeDescription
sourceLanguagestringThe IETF language code of the source text (e.g., ‘en’ for English)
targetLanguagestringThe IETF language code for the target language (e.g., ‘es’ for Spanish). This is also used to name the new field
sheetSlugstringThe slug of the sheet that the plugin should listen to. Records from other sheets will be ignored
fieldsToTranslatestring[]An array of field keys (names) that should be translated. The plugin will only process these fields
projectIdstringYour Google Cloud project ID associated with the Google Translate API
keyFilenamestringThe absolute or relative path to your Google Cloud service account key file (JSON)

​
Default Behavior

By default, the plugin does not do anything until it is configured and registered with a Flatfile listener. Once configured, it will listen for record processing events on the specified sheetSlug. For each record, it will read the text from the fieldsToTranslate, call the Google Translate API, and write the results to new fields. If a field to be translated is empty or null, it is skipped.

​
Usage Examples

​
Basic Usage

import { FlatfileListener } from '@flatfile/listener';
import { convertTranslatePlugin } from '@flatfile/plugin-convert-translate';

export default function (listener) {
  listener.use(
    convertTranslatePlugin({
      sourceLanguage: 'en',
      targetLanguage: 'fr',
      sheetSlug: 'contacts',
      fieldsToTranslate: ['notes', 'comments'],
      projectId: 'your-gcp-project-id',
      keyFilename: './gcp-credentials.json',
    })
  );
}

​
Multiple Language Translation

To translate to multiple languages, use the plugin multiple times with different configurations:

import { FlatfileListener } from '@flatfile/listener';
import { convertTranslatePlugin } from '@flatfile/plugin-convert-translate';

export default function (listener) {
  // Translate to Spanish
  listener.use(
    convertTranslatePlugin({
      sourceLanguage: 'en',
      targetLanguage: 'es',
      sheetSlug: 'products',
      fieldsToTranslate: ['name', 'description'],
      projectId: 'your-gcp-project-id',
      keyFilename: './gcp-credentials.json',
    })
  );

  // Translate to German
  listener.use(
    convertTranslatePlugin({
      sourceLanguage: 'en',
      targetLanguage: 'de',
      sheetSlug: 'products',
      fieldsToTranslate: ['name', 'description'],
      projectId: 'your-gcp-project-id',
      keyFilename: './gcp-credentials.json',
    })
  );
}

​
Manual Translation with translateRecord

import { translateRecord, convertTranslatePlugin } from '@flatfile/plugin-convert-translate';

const config = {
  sourceLanguage: 'en',
  targetLanguage: 'ja',
  sheetSlug: 'articles',
  fieldsToTranslate: ['title'],
  projectId: 'your-gcp-project-id',
  keyFilename: './gcp-credentials.json',
};

// Initialize the client (required for translateRecord to work)
convertTranslatePlugin(listener, config);

// Manually process a record
record.set('title', 'Hello World');
const { record: updatedRecord, error } = translateRecord(record, config);

if (error) {
  console.error('Translation failed:', error);
} else {
  const translatedTitle = updatedRecord.get('title_ja');
  console.log(translatedTitle); // Expected to be the Japanese translation
}

​
API Reference

​
convertTranslatePlugin

The main entry point for the plugin. This function registers a recordHook with the provided Flatfile listener, which will automatically translate specified fields on records belonging to the configured sheet.

Signature:

convertTranslatePlugin(listener: FlatfileListener, config: TranslationConfig): void

Parameters:

  • listener: FlatfileListener - An instance of a Flatfile listener to attach the hook to
  • config: TranslationConfig - The configuration object for the plugin

Returns: void - This function does not return a value. It modifies the listener instance directly.

​
translateRecord

A standalone function that applies the translation logic to a single FlatfileRecord. It reads values from the fields specified in the config, translates them, and sets the translated values on new fields in the record.

Signature:

translateRecord(record: FlatfileRecord, config: TranslationConfig): { record: FlatfileRecord; error?: string }

Parameters:

  • record: FlatfileRecord - The record to process
  • config: TranslationConfig - A configuration object specifying languages, fields, and credentials

Returns: An object containing:

  • record: FlatfileRecord - The record with new fields containing translated text
  • error?: string - An error message if an issue occurred during processing

​
Troubleshooting

​
Error Handling

The plugin includes comprehensive error handling:

  • API Errors: If the Google Translate API call fails, the error is logged to the console and the record won’t be updated with translated values
  • Record-level Errors: If an error occurs during processing of a single record, the plugin will attach a general error message to that specific record using record.addError(), making it visible in the Flatfile UI
  • No Text to Translate: If a record has no text in any of the fieldsToTranslate, it is skipped without error
// Error handling example
const { record: updatedRecord, error } = translateRecord(record, config);

if (error) {
  // This adds the error to the record, which is visible to the user
  updatedRecord.addError('general', error);
}

return updatedRecord;

​
Notes

​
Requirements

  • Google Cloud Account: A Google Cloud project with the Translate API enabled is required
  • Credentials: You must provide a valid projectId and a path to a service account keyFilename with appropriate permissions

​
Field Naming Convention

The plugin creates new fields for translated content by appending _{targetLanguage} to the original field name (e.g., name becomes name_es). Ensure this does not conflict with existing fields in your sheet configuration.

​
Limitations

  • Field Types: The plugin is designed to work with string fields. Behavior with other field types is undefined
  • Initialization: The Google Translate client is initialized globally within the plugin’s scope when convertTranslatePlugin is first called. Subsequent calls with different credentials will re-initialize the client