Package com.veeva.vault.sdk.api.translation
Overview
All supported translation operations go throughFileTranslationService.
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
- Submit batches of files for translation by an external provider
- Retrieve translated files in a post-processing event handler
Key Interfaces
FileTranslationService: The main service for submitting translation batches. Use this to get instances of other translation interfaces and to submit a batch for translation.FileTranslationInput: Represents a single file to translate, along with its source and target languages.FileTranslationBatchRequest: Groups one or moreFileTranslationInputobjects with a shared provider connection, event handler, and optional parameters.DocumentCreationHandlerParameters: The set of parameters required by the platform-provideddocument_creation__sysevent handler, which creates a new translated document per translated file.DocumentUpdateHandlerParameters: The set of parameters required by the platform-provideddocument_update__sysevent handler, which creates a new version of an existing target document from the translated content.
FileTranslationBatchOperation: Returned byFileTranslationService.batchTranslateFiles(com.veeva.vault.sdk.api.translation.FileTranslationBatchRequest)and used to specify how pre-queue validation errors are handled before the batch is submitted.FileTranslationEventHandler: The entry point for processing translation results once a batch run finishes.FileTranslationEventHandlerContext: Passed toFileTranslationEventHandler.onCompleteWithSuccess(com.veeva.vault.sdk.api.translation.FileTranslationEventHandlerContext)orFileTranslationEventHandler.onCompleteWithError(com.veeva.vault.sdk.api.translation.FileTranslationEventHandlerContext), providing both the successfully translated results and the failed results, along with the rehydrated batch-level parameters.
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 viaBatchOperation.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 ofFileTranslationEventHandler.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 ownFileTranslationEventHandler,
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 singleFileTranslationBatchRequest 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.-
ClassDescriptionHolds the parameters for the platform-provided
document_creation__systranslation event handler, which creates a new translated document per successfully translated file in the batch, copying fields from a source document version and linking each translation back to it.Builder for constructingDocumentCreationHandlerParameters.Holds the parameters for the platform-provideddocument_update__systranslation event handler, which creates a new version of an existing target document from the translated content.Builder for constructingDocumentUpdateHandlerParameters.Represents the batch operation returned byFileTranslationService.batchTranslateFiles(FileTranslationBatchRequest), used to specify how pre-queue validation errors are handled before the batch is submitted.Encapsulates all inputs required to submit a batch of files for translation viaFileTranslationService.batchTranslateFiles(FileTranslationBatchRequest).Builder for constructing aFileTranslationBatchRequest.Valid values forFileTranslationSubmissionError.getErrorType(), classifying the reason aFileTranslationInputwas rejected during pre-queue validation in aFileTranslationBatchOperation.Represents the SDK entry point invoked by the platform after a translation batch run completes.Represents the context passed toFileTranslationEventHandler.onCompleteWithSuccess(FileTranslationEventHandlerContext)orFileTranslationEventHandler.onCompleteWithError(FileTranslationEventHandlerContext)after a translation batch run finishes.Indicates a class is aFileTranslationEventHandlerand declares the API name by which the platform identifies it.Represents a single file to translate within aFileTranslationBatchRequest.Builder for constructing aFileTranslationInput.Represents a keyed, serializable collection of parameters carried at the batch level across the async translation boundary.Builder for constructing aFileTranslationParametersinstance.Represents a marker interface for custom parameter value objects that can be stored in aFileTranslationParametersinstance and retrieved in aFileTranslationEventHandler.Represents a type token used to specify the expected Java type when reading a scalar parameter value fromFileTranslationEventHandlerContext.getParameter(String, FileTranslationParameterValueType).Represents the common base for the parameters objects read by the platform-provided translation event handlers (document_creation__sysanddocument_update__sys).Valid values forFileTranslationResultError.getErrorType(), classifying provider-level failures for positional results that failed during the asynchronous translation run.Represents an individual error result contained withinFileTranslationEventHandlerContext.getErrors()for aFileTranslationInputthat failed during the asynchronous translation run.Represents an individual success result contained withinFileTranslationEventHandlerContext.getResults()for aFileTranslationInputthat was successfully translated.Provides the service for submitting batches of files to an external translation provider.Represents a positional input that failed pre-queue validation in aFileTranslationBatchOperation.Represents a successfully queued positional input in aFileTranslationBatchOperation.