How to Localize API Documentation into Japanese? Using Machine Translation and Human Translation Appropriately

When expanding overseas APIs and SaaS into the Japanese market, preparing Japanese API documentation is an important theme. API documentation is not just explanatory material. It is a practical infrastructure for developers to implement, verify, troubleshoot, and facilitate internal adoption decisions.

While Japanese developers often have opportunities to read technical information in English, not all developers are proficient in English. Especially for documents like API specifications, where it is necessary to accurately understand detailed conditions, restrictions, exceptions, permissions, and error contents, differences in English comprehension directly affect the quality of implementation and development speed.

Therefore, API documents that can be accurately read in Japanese are not just a matter of convenience but an essential requirement for having APIs used in the Japanese market. On the other hand, translating all documents manually from the start requires time and cost. This is where a translation workflow combining machine translation and human translation becomes effective.

Reference blog: Evaluating the Performance of Generative AI Translation in 6 Languages [ChatGPT vs Human Translation Comparison Report]

This article explains the importance of API document translation, common file formats used for API documents, common issues that occur with existing machine-translated documents, and practical translation workflows combining machine translation and human translation.

1. The Importance of Localizing API Documentation into Japanese

By localizing API documentation into Japanese, the burden on developers' understanding is reduced. If authentication methods, request formats, response specifications, error handling, and limitations can be checked in Japanese, it becomes easier to reduce misreading or missed confirmations during implementation.

Even developers who are accustomed to reading technical documents in English need time to thoroughly understand the details of the specifications without hesitation. For developers who are not proficient in English, the burden of research and verification is even greater. Japanese documentation not only speeds up development but also helps reduce implementation errors and support inquiries.

Also, having Japanese documentation makes it easier to share specifications not only with the development team but also with PMs, QA, support, sales, legal, and security personnel. Japanese localization holds great significance when considering API adoption and advancing internal approvals.

2. In What Format Are API Documents Managed?

API documentation is not necessarily managed as a single document like a Word file. In fact, it is often created by combining multiple formats, and behind the HTML visible on the public site, there are Markdown files, OpenAPI definitions, source code comments, and more.

The main content such as guides, quick starts, tutorials, and conceptual explanations is often written in Markdown or MDX. This is because they are easy to manage on GitHub or GitLab and are compatible with documentation site generators like Docusaurus, Next.js, and others.

On the other hand, REST API references are generally generated from OpenAPI or Swagger YAML/JSON files. They are written in a format that software can read, including endpoints, parameters, responses, status codes, authentication methods, and so on, and reference pages are generated based on that information.

In SDK and library documentation, there are cases where explanatory text is generated from comments within the source code. Typical examples include JavaDoc, TSDoc, JSDoc, docstrings, and XML comments. In other words, API documentation translation may involve not only the Markdown main text but also OpenAPI definitions and explanations derived from source code.

In this way, API documentation is generally composed of multiple sources, such as "main text documents in Markdown, API specifications in OpenAPI YAML/JSON, and SDK explanations in source code comments." Therefore, a translation workflow different from that of ordinary document translation is required.

3. Why API Documentation Translation Differs from General Translation

In API documentation translation, it is not enough to simply produce natural Japanese. There are many elements that must not be translated, such as Markdown headings and code blocks, OpenAPI JSON keys, YAML structures, endpoint names, parameter names, sample responses, and SDK class and method names.

For example, explanations in the main text should be translated into Japanese, but endpoints like GET /users/{id}, parameter names like client_id, and JSON keys like statusCode should, in principle, not be changed. If these are translated, developers will not be able to use them directly for implementation.

Furthermore, Markdown and MDX may include links, tables, code fences, and component calls. OpenAPI YAML and JSON have a strict structure as specification definitions. In the case of source code comments, it is important not to break the correspondence between the code and the explanatory text.

Therefore, API documentation translation requires not only translation quality but also processing that understands file formats and document structures. Distinguishing between parts that should be translated and parts that should not is a prerequisite for creating Japanese documentation that can be used for implementation.

4. Common Issues in Existing Machine-Translated API Documentation

As seen in the API documentation of major software companies, there are challenges with Japanese documents produced by machine translation. One common issue is inconsistency in the translation of technical terms. When the same concept is translated differently across pages, users find it difficult to determine whether they refer to the same thing or different things.

Additionally, API names, method names, property names, JSON keys, permission names, configuration items, and other terms that should originally be kept in English are sometimes translated. This makes it difficult to correlate code samples with the main text explanations and also reduces searchability.

Terms such as request, response, resource, endpoint, tenant, scope, permission, and deprecated need to be translated differently depending on the API context. If they are translated as general words without considering the context, their meaning becomes unclear, making it difficult to make implementation decisions.

Furthermore, if expressions indicating obligation, requirement, or prohibition such as must, required, and do not are not translated clearly, there is a risk of misunderstanding the importance in the specifications. Such mistranslations in areas like authentication, permissions, billing, restrictions, and deprecation information can lead to troubles after implementation.

It is also problematic when the Japanese version cannot keep up with updates to the English version. If the Japanese version remains outdated and is not updated, issues may arise in the software implementation.

5. The Value of Machine Translation in Quickly Providing the Latest Information

On the other hand, it is not that machine translation itself has no value. For content like API documentation, which has many pages and a high update frequency, the speed of machine translation is a significant advantage.

Quickly localizing new pages into Japanese, reflecting update differences in a short time, and first making the entire content readable in Japanese are practically impossible with human translation alone. For developers who are not proficient in English, having an overview available in Japanese first is far more meaningful than leaving it untranslated.

It is important to recognize that machine translation is not the final version. In API documentation, merely "roughly understanding the meaning" is insufficient. Since developers write code, configure settings, and handle troubleshooting based on the text, accuracy, consistency, searchability, and synchronization with the original English text are required.

6. Hybrid Workflow Combining Machine Translation and Human Translation

First, machine translate the entire content, then have humans refine the important parts

A practical and effective approach is to quickly perform an initial translation using machine translation, then have humans review and correct the critical sections. Instead of translating everything manually from the start, this method shortens the information gap period while focusing human resources on high-risk areas.

High-priority topics include authentication, security, permissions, billing, personal information, limitations, breaking changes, deprecated information, error handling, main endpoints, SDK setup procedures, and so on. Supplementary explanations and reference information can first be provided via machine translation, with improvements made later as needed.

Protect elements that should not be translated

In API documentation, it is important to structurally separate the main text, headings, tables, code blocks, parameter names, response examples, error messages, links, and so on. Depending on the format such as Markdown, MDX, OpenAPI YAML/JSON, or source code comments, distinguish between parts that can be translated and parts that should be protected.

If this process can be automated, it becomes easier to prevent issues where code or configuration items are altered by translation. In API documentation translation, not only how sentences are translated but also a system that safely handles document structure determines the quality.

Maintain consistency with glossaries and automated quality checks

Terms such as endpoint, resource, scope, tenant, permission, and deprecated need to have their translations predefined according to the API context. Applying a glossary to machine translation helps suppress inconsistencies in terminology across different pages.

Additionally, we check whether code blocks have been altered, whether API names or JSON keys have been translated, whether numbers, limits, or version numbers have changed, and whether mandatory or prohibitive expressions have been weakened. In recent years, mechanical reviews using generative AI have become possible, and by performing mechanical checks before manual reviews, the efficiency of quality assurance can be improved.

Clearly Indicate Translation Status

When publishing the Japanese version of the document, clearly indicating statuses such as "Machine Translated," "Human Reviewed," "Technical Review Completed," and "Pending Reconfirmation Due to Source Update" helps readers better assess the reliability of the information.

Links to the original English text are also important. Especially for machine-translated pages that have not been reviewed, providing a way to check the original text as needed can reduce users' concerns.

7. API Document Translation Supported by MTrans

MTrans is a machine translation service provided by our company, Human Science. It supports translation workflows to efficiently multilingualize technical content such as API documents. It can be utilized with an eye on operations important for API document translation, including rapid initial translation by machine translation, terminology control through glossaries, protection of non-translatable elements, tracking of source text updates, and collaboration with human reviews.

MTrans is an effective option when you want to deploy English API documents for the Japanese market, improve the quality of existing machine-translated documents, or when frequent updates make it difficult to keep up with human translation alone.

It is especially suitable for companies facing challenges such as wanting to translate without breaking API names, code, or parameter names; aiming to translate with awareness of technical document structures like Markdown and OpenAPI; maintaining terminology consistency; applying human review only to important pages; and utilizing the Japanese version of documents for sales, implementation support, and customer support.

8. Combining with Human Translation Services to Create Japanese Documents Usable for Implementation

Ultimately, the quality of API documentation is supported by human judgment. The selection of technical terms, context-appropriate translation distinctions, verification of expressions important to the specifications, consistency between code and explanatory text, and readability in Japanese are greatly improved through the eyes of technical translators and reviewers.

Human Science also offers human translation and post-editing services tailored for API documents and technical documents. By quickly preparing the Japanese version with machine translation and having experts review and correct important pages, we can achieve a balance between speed and quality.

Providing documentation that Japanese developers can use for implementation without hesitation leads to expanded API usage, reduced support burden, and promotion of adoption consideration. Rather than just simple translation, please consider combining machine translation and human translation services as a foundation for enabling API usage in the Japanese market.

Reference site: Post-Editing (MTPE) | Machine Translation | Human Science, a Widely Accomplished Translation Company

9. Summary

Localizing API documentation into Japanese is important for Japanese developers to accurately understand the specifications and proceed smoothly with implementation. Even developers who frequently read technical information in English are not all proficient in English, and misreading the specifications can lead to implementation errors and delays in adoption.

API documentation often consists of multiple formats such as Markdown, OpenAPI YAML/JSON, and source code comments. Machine translation offers great value in providing rapid delivery and keeping up with updates. However, to achieve quality suitable for practical use, terminology management, protection of non-translatable elements, automated quality checks, and human review are indispensable.

By combining MTrans with human translation services, it becomes easier to achieve both the speed of machine translation and the accuracy of human translation. If you are having trouble with Japanese localization of API documents or improving the quality of existing translations, please do not hesitate to consult Human Science.

Reference link: Translation Service Companies – Numerous Achievements | Human Science