# AI.TRANSLATE ## Content Users can use the AI.TRANSLATE function to translate given content into the target language. ## Syntax `AI.TRANSLATE(array, language)` ## Arguments This function has these arguments: | **Argument** | **Description** | | -------- | ----------- | | *array* | [Required] The array or range to be translated. | | *language* | [Required] The specified target language. | ## Remarks When setting the `language` parameter, it is recommended to use standard locale codes (such as RFC 5646), or clear and understandable language names. This helps ensure system compatibility, data consistency, and accurate results in globalization scenarios. **Common language code samples:** * en-US / English * zh-CN / Chinese / 中文 * ja-JP / Japanese / 日本語 * ko-KR / Korean / 한국어 * fr-FR / French / Français ## Examples The following example shows how to invoke the OpenAI GPT-4.1 model and use the AI.TRANSLATE function for single sentence and batch text translation. ```java // To use this example, add the following dependency to your project: com.openai:openai-java:4.6.1 // Configure the model request handler and choose different large model providers as needed. Here the example uses OpenAI GPT-4.1; replace with your API key when using. Workbook.setAIModelRequestHandler(new OpenAIModelRequestHandler("https://api.openai.com/v1", "sk-xxxx", "gpt-4.1")); // DeepSeek model. // Workbook.setAIModelRequestHandler(new OpenAIModelRequestHandler("https://api.deepseek.com/v1", "sk-xxxx", "deepseek-chat")); // Qwen model. // Workbook.setAIModelRequestHandler(new OpenAIModelRequestHandler("https://dashscope.aliyuncs.com/compatible-mode/v1", "sk-xxxx", "qwen-plus")); // Initialize the workbook and set data. Workbook workbook = new Workbook(); IWorksheet sheet = workbook.getWorksheets().get(0); sheet.getColumns().get(0).setColumnWidth(40); sheet.getColumns().get(1).setColumnWidth(20); sheet.getColumns().get(2).setColumnWidth(45); // ============ Example 1: Single Text Translation ============ sheet.getRange("A1:C1").merge(); sheet.getRange("A1").setValue("Example 1: Single Text Translation"); sheet.getRange("A1").getFont().setBold(true); sheet.getRange("A1").getFont().setSize(14); sheet.getRange("A1").getFont().setColor(Color.GetWhite()); sheet.getRange("A1").getInterior().setColor(Color.FromArgb(90, 126, 158)); sheet.getRange("A1").setHorizontalAlignment(HorizontalAlignment.Center); sheet.getRange("A1").setVerticalAlignment(VerticalAlignment.Center); sheet.getRange("A1").setRowHeight(30); sheet.getRange("A3").setValue("Formula:"); sheet.getRange("A3").getFont().setBold(true); sheet.getRange("A3").getFont().setSize(11); sheet.getRange("A3").getInterior().setColor(Color.FromArgb(217, 225, 242)); sheet.getRange("B3:C3").merge(); sheet.getRange("B3").setValue("=AI.TRANSLATE(A6, B6)"); sheet.getRange("B3").getFont().setItalic(true); sheet.getRange("B3").getFont().setColor(Color.FromArgb(68, 114, 196)); sheet.getRange("A5:C5").setValue(new Object[][] { { "Source Text (English)", "Target Lang", "AI Translation" } }); sheet.getRange("A5:C5").getFont().setBold(true); sheet.getRange("A5:C5").getInterior().setColor(Color.FromArgb(155, 194, 230)); sheet.getRange("A5:C5").setHorizontalAlignment(HorizontalAlignment.Center); sheet.getRange("A6").setValue("Hello, how are you today?"); sheet.getRange("B6").setValue("ja-JP"); sheet.getRange("B6").getFont().setBold(true); sheet.getRange("B6").setHorizontalAlignment(HorizontalAlignment.Center); // Define AI translation formula to translate the text in A6 to the target language specified in B6. sheet.getRange("C6").setFormula2("=AI.TRANSLATE(A6, B6)"); sheet.getRange("C6").getFont().setItalic(true); sheet.getRange("C6").getFont().setSize(11); sheet.getRange("A6:C6").getBorders().setLineStyle(BorderLineStyle.Thin); sheet.getRange("A6:C6").getBorders().setColor(Color.FromArgb(200, 200, 200)); // ============ Example 2: Batch Translation ============ sheet.getRange("A9:C9").merge(); sheet.getRange("A9").setValue("Example 2: Batch Translation (English → Japanese)"); sheet.getRange("A9").getFont().setBold(true); sheet.getRange("A9").getFont().setSize(14); sheet.getRange("A9").getFont().setColor(Color.GetWhite()); sheet.getRange("A9").getInterior().setColor(Color.FromArgb(90, 126, 158)); sheet.getRange("A9").setHorizontalAlignment(HorizontalAlignment.Center); sheet.getRange("A9").setVerticalAlignment(VerticalAlignment.Center); sheet.getRange("A9").setRowHeight(30); sheet.getRange("A11").setValue("Formula:"); sheet.getRange("A11").getFont().setBold(true); sheet.getRange("A11").getFont().setSize(11); sheet.getRange("A11").getInterior().setColor(Color.FromArgb(217, 225, 242)); sheet.getRange("B11:C11").merge(); sheet.getRange("B11").setValue("=AI.TRANSLATE(A14:A18, B14)"); sheet.getRange("B11").getFont().setItalic(true); sheet.getRange("B11").getFont().setColor(Color.FromArgb(68, 114, 196)); sheet.getRange("A13:C13").setValue(new Object[][] { { "Source Text (English)", "Target Lang", "AI Translation (Japanese)" } }); sheet.getRange("A13:C13").getFont().setBold(true); sheet.getRange("A13:C13").getInterior().setColor(Color.FromArgb(155, 194, 230)); sheet.getRange("A13:C13").setHorizontalAlignment(HorizontalAlignment.Center); sheet.getRange("A14:A18").setValue(new Object[][] { { "Good morning!" }, { "Thank you very much." }, { "How much does this cost?" }, { "Where is the nearest restaurant?" }, { "Have a nice day!" } }); sheet.getRange("A14:C18").getBorders().setLineStyle(BorderLineStyle.Thin); sheet.getRange("A14:C18").getBorders().setColor(Color.FromArgb(200, 200, 200)); sheet.getRange("B14").setValue("ja-JP"); sheet.getRange("B14:B18").merge(); sheet.getRange("B14").getFont().setBold(true); sheet.getRange("B14").getFont().setSize(12); sheet.getRange("B14").setHorizontalAlignment(HorizontalAlignment.Center); sheet.getRange("B14").setVerticalAlignment(VerticalAlignment.Center); sheet.getRange("B14:B18").getBorders().setLineStyle(BorderLineStyle.Thin); sheet.getRange("B14:B18").getBorders().setColor(Color.FromArgb(200, 200, 200)); // Define AI translation formula to translate the text in A14:A18 into the target language specified in B14. sheet.getRange("C14").setFormula2("=AI.TRANSLATE(A14:A18, B14)"); sheet.getRange("C14:C18").getFont().setItalic(true); sheet.getRange("A1:C7").getBorders().get(BordersIndex.EdgeBottom).setLineStyle(BorderLineStyle.Double); sheet.getRange("A1:C7").getBorders().get(BordersIndex.EdgeBottom).setColor(Color.FromArgb(142, 172, 219)); // The AI function works as an asynchronous calculation function; you need to wait for its calculation to complete. workbook.calculate(); workbook.waitForCalculationToFinish(); // Set the page to print as a single page. sheet.getPageSetup().setFitToPagesTall(1); sheet.getPageSetup().setFitToPagesWide(1); sheet.getPageSetup().setIsPercentScale(false); // Save as PDF file. workbook.save("AITranslate.pdf"); ``` ```java /** * Implementation of IAIModelRequestHandler for OpenAI API. */ public class OpenAIModelRequestHandler implements IAIModelRequestHandler { private String _apiEndpoint; private String _apiKey; private String _model; public OpenAIModelRequestHandler(String apiEndpoint, String apiKey, String model) { if (apiEndpoint == null || apiEndpoint.trim().isEmpty()) throw new IllegalArgumentException("API endpoint cannot be null or empty."); if (apiKey == null || apiKey.trim().isEmpty()) throw new IllegalArgumentException("API key cannot be null or empty."); _apiEndpoint = apiEndpoint.replaceAll("/$", ""); _apiKey = apiKey; _model = model; } @Override public CompletableFuture sendRequestAsync(AIModelRequest request) { CompletableFuture result = new CompletableFuture<>(); if (request == null) { AIModelResponse modelResponse = new AIModelResponse(); modelResponse.setSuccess(false); System.err.println("Request cannot be null."); result.complete(modelResponse); return result; } OpenAIClientAsync openAIClient = OpenAIOkHttpClientAsync.builder() .apiKey(_apiKey) .baseUrl(_apiEndpoint) .build(); ChatCompletionCreateParams.Builder builder = ChatCompletionCreateParams.builder(); for (AIMessage item : request.getMessages()) { switch (item.getRole().toLowerCase()) { case "system": builder.addSystemMessage(item.getContent()); break; case "user": builder.addUserMessage(item.getContent()); break; default: throw new RuntimeException("Unknown message role:" + item.getRole()); } } builder.model(_model); ChatCompletionCreateParams params = builder.build(); CompletableFuture chatCompletion = openAIClient.chat().completions().create(params); chatCompletion.whenComplete((response, exception) -> { try { if (exception != null) { AIModelResponse errorResponse = new AIModelResponse(); errorResponse.setSuccess(false); System.err.println("An error occurred: " + exception.getMessage()); result.complete(errorResponse); } else { if (response != null && !response.choices().isEmpty()) { StringBuilder contentBuilder = new StringBuilder(); for (ChatCompletion.Choice choice : response.choices()) { choice.message(); if (choice.message().content().isPresent()) { contentBuilder.append(choice.message().content().get()); } } AIModelResponse successResponse = new AIModelResponse(); successResponse.setSuccess(true); successResponse.setContent(contentBuilder.toString()); result.complete(successResponse); } else { AIModelResponse noContentResponse = new AIModelResponse(); noContentResponse.setSuccess(false); System.err.println("No content received from the model."); result.complete(noContentResponse); } } } finally { try { openAIClient.close(); } catch (Exception e) { System.err.println("Error closing OpenAI client: " + e.getMessage()); } } }); return result; } } ``` The output is shown below: ![image](https://cdn.mescius.io/document-site-files/images/7466bdc8-02f8-494c-b60a-49ddbe7c10d4/image.77e652.png)