Package com.veeva.vault.sdk.api.translation


package com.veeva.vault.sdk.api.translation
This package provides services and interfaces for submitting files to an external translation provider and processing the translated output.

Overview

All supported translation operations go through FileTranslationService. This service builds and submits batches of files for translation and provides methods to construct the inputs and parameters needed to do so.

Translation is asynchronous. You first build one FileTranslationInput per file, group them into a FileTranslationBatchRequest, and submit the batch via FileTranslationService.batchTranslateFiles(com.veeva.vault.sdk.api.translation.FileTranslationBatchRequest). The platform queues each input and, once the run finishes, invokes a FileTranslationEventHandler implementation with the results.

FileTranslationService is designed to be general purpose and as such can be called from Vault actions such as RecordAction and DocumentAction.

Two distinct error layers can occur along the way: pre-queue validation errors, problems with the request itself detected before a file is ever queued (see Submitting Files for Translation), and provider-level errors, failures that occur later while the external provider performs the translation (see Processing Translation Results).

Key Functionality

Key Interfaces

Submitting Files for Translation

The following example builds a single-file translation request and submits it. Submission can fail with a pre-queue validation error for a problem with the request itself, for example an inactive provider connection, an unreadable source file, or a target language the provider doesn't support. These are reported per input via BatchOperation.onErrors(java.util.function.Consumer) before the batch is queued, while successfully validated inputs are still queued for translation.
  
      FileTranslationService translationService = ServiceLocator.locate(FileTranslationService.class);

      // Build the input for a single file
      FileTranslationInput input = translationService.newFileTranslationInputBuilder()
              .withSourceFile(sourceFileReference)
              .withTargetLanguageCode("es")
              .build();

      // Build the batch request
      FileTranslationBatchRequest request = translationService.newFileTranslationBatchRequestBuilder()
              .withFileTranslationInputs(VaultCollections.asList(input))
              .withConnectionName("deepl")
              .withEventHandlerApiName("my_translation_handler__c")
              .build();

      // Submit the batch
      translationService.batchTranslateFiles(request)
              .onErrors(errors -> {
                  for (FileTranslationSubmissionError error : errors) {
                      // Log or handle error here
                  }
              })
              .execute();
  
 

Processing Translation Results

A given file's result is either the translated output file, or, if that file could not be translated, a provider-level error describing why, for example the provider was temporarily unreachable, rejected the request due to expired credentials, or failed to translate the file for reasons specific to that provider. Exactly one of FileTranslationEventHandler.onCompleteWithSuccess(com.veeva.vault.sdk.api.translation.FileTranslationEventHandlerContext) or FileTranslationEventHandler.onCompleteWithError(com.veeva.vault.sdk.api.translation.FileTranslationEventHandlerContext) is called per batch run, but both use the same FileTranslationEventHandlerContext: onCompleteWithSuccess is called only when every input in the batch succeeded, while onCompleteWithError is called if any input failed, even if other inputs in the same batch succeeded.

Results can be processed either by an SDK-authored FileTranslationEventHandler (see below), or by one of the platform-provided result handlers, which cover the two most common outcomes — creating a new document or up-versioning an existing one — without requiring any SDK code.

Example: Implementing a Translation Event Handler

The following example retrieves each successfully translated file, and separately handles the provider error for each file that failed.
  
      import com.veeva.vault.sdk.api.translation.*;

      @FileTranslationEventHandlerInfo(apiName = "my_translation_handler__c")
      public class MyTranslationHandler implements FileTranslationEventHandler {

          @Override
          public void onCompleteWithSuccess(FileTranslationEventHandlerContext context) {
              for (FileTranslationResultSuccess result : context.getResults()) {
                  // Retrieve the successfully translated file
                  FileReference translatedFile = result.getFileReference();
              }
          }

          @Override
          public void onCompleteWithError(FileTranslationEventHandlerContext context) {
              for (FileTranslationResultSuccess result : context.getResults()) {
                  // Retrieve the successfully translated file
                  FileReference translatedFile = result.getFileReference();
              }
              for (FileTranslationResultError result : context.getErrors()) {
                  // Log or handle error here
              }
          }
      }
  
 

Using a Platform-Provided Result Handler

Instead of implementing your own FileTranslationEventHandler, you can pass the API name of one of the platform-provided result handlers to FileTranslationBatchRequest.Builder.withEventHandlerApiName(java.lang.String):
  • DocumentCreationHandlerParameters.API_NAME: creates a new translated document per successfully translated file, copying fields from a source document version and linking each translation back to it.
  • DocumentUpdateHandlerParameters.API_NAME: creates a new version of an existing target document from the translated content. Only appropriate when a single target language is selected and the batch has exactly one input.

Each platform handler needs its corresponding parameters. Build the DocumentCreationHandlerParameters or DocumentUpdateHandlerParameters instance via FileTranslationService and attach it to the batch's FileTranslationParameters under the handler's PARAMETER_NAME, so the platform can rehydrate it once the batch completes:

  
      DocumentCreationHandlerParameters handlerParameters = translationService
              .newDocumentCreationHandlerParametersBuilder()
              .withInstanceId("1000443")
              .withSourceDocumentId("1502")
              .withSourceMajorVersion("1")
              .withSourceMinorVersion("0")
              .withTargetLanguageCodes(VaultCollections.asList("fr", "de"))
              .withNotifyOnCompletion(true)
              .build();

      FileTranslationParameters parameters = translationService.newFileTranslationParametersBuilder()
              .appendValue(DocumentCreationHandlerParameters.PARAMETER_NAME, handlerParameters)
              .build();
              
      FileTranslationInput input = translationService.newFileTranslationInputBuilder()
              .withSourceFile(sourceFileReference)
              .withTargetLanguageCode("es")
              .build();

      FileTranslationBatchRequest request = translationService.newFileTranslationBatchRequestBuilder()
              .withFileTranslationInputs(VaultCollections.asList(input))
              .withConnectionName("deepl")
              .withEventHandlerApiName(DocumentCreationHandlerParameters.API_NAME)
              .withParameters(parameters)
              .build();
  
 

See DocumentCreationHandlerParameters and DocumentUpdateHandlerParameters for the full set of parameters each platform handler requires.

Best Practices

A single FileTranslationBatchRequest may contain at most 500 FileTranslationInput entries. Requests exceeding this limit fail pre-queue validation. Group files into batches at or under this limit rather than submitting one file per batch, to reduce network overhead and improve efficiency.