Introduction

Since the early days of NearMe, our team has included both Japanese- and English-speaking members, and we struggled to decide whether development documentation should be written in English or Japanese. As a result, documents ended up mixed between the two languages. In that state, we could not say our documentation was sufficiently organized.

Against this backdrop, recent advances in AI have significantly improved translation quality, making multilingual documentation much easier. With that in mind, we revisited the foundation of our development documentation and pushed forward with multilingual support. In this article, I will share what we implemented.

How We Managed Documentation Before

We already had a fair amount of development-related information, although it was scattered. On Git, we tried to include README files and code comments as much as possible, and all of those were written in English. Information related to design and operations was written more informally in Notion. However, documents in Notion were primarily in Japanese, with only some translated into English. Also, documentation authors tended to be limited to system designers or a small number of specific members.

We had always needed a systematic documentation platform that could serve as primary source information, but multilingual support was a major challenge.

Rebuilding the Documentation Site

This time, we rebuilt our development documentation as an Astro-based site. Documents are managed in Markdown and version-controlled on Git. We chose Astro because of its simple structure, strong compatibility with Markdown, and ease of multilingual implementation.

Notion also provides translation features, and we still use them in some cases. However, managing documentation in Markdown makes it easier to edit in tools like VS Code and to leverage AI not only for translation but also for improving writing quality, so we chose a Markdown-based workflow.

For multilingual support, we went further than using AI only inside the editor and automated the process with GitHub Actions. When a pull request is created or updated, GitHub Actions is triggered, runs AI-based translation, and commits the translation results. At a high level, we give AI the following instructions:

• From the diff against the base branch, extract only changed Japanese/English documentation files
• For each changed file, create or update the corresponding file in the other language
• Do not read or modify files other than the changed file and its counterpart
• Preserve existing body text by default, and update only metadata version when needed
• Translate title and description; use natural polite style in Japanese and concise direct style in English
• Compare version with the base branch; if the author did not bump it, increment the changed side by +1 and align the counterpart to the same value
• Replace internal link language paths (Japanese/English) in both directions
• Replace language suffixes in image names as needed (for example, -ja and -en)
• Do not translate code blocks; keep them as-is

In short, we automatically keep Japanese and English versions aligned only for documents that changed, without breaking translation quality or version consistency.

As a supporting tool, we also prepared a script that detects and lists metadata version differences.

What We Learned in Operation

In terms of translation quality, thanks to AI improvements, it has reached a practical level with almost no manual fixes needed.

Even for documents that we previously wrote directly in English, being able to draft carefully in our native language first has improved overall document quality. Also, because writing documentation now feels less burdensome, we have been able to preserve more knowledge as documentation.

There are still many documents left to organize, but at least we now have an environment where recording information is much easier.

Bringing the Tech Blog onto the Same Platform

The framework we built this time is not limited to development documentation; we also applied it to our tech blog here. Originally, the tech blog was managed on a separate service, but to improve multilingual support and unify operations, we migrated it to the same Astro-based platform. Because we could reuse the mechanisms built for development documentation, and because we implemented the migration while leveraging AI, we completed the migration in a short period. As a result, we can now operate both development documentation and the tech blog using the same foundation.

Conclusion

As AI continues to advance, not only translation costs but also the costs of site development and operational infrastructure are dropping significantly. In this effort, a major outcome was not only multilingual support but also establishing a foundation that enables continuous documentation. As AI-driven development becomes more common, the importance of development documentation will continue to grow. By leveraging the platform we built, we plan to keep expanding our documentation going forward.