jsii-rosetta Explanation

jsii-rosetta is a tool that automatically translates code examples from TypeScript into other programming languages. If you're building a library in TypeScript that you want developers in Python, Java, C#, or Go to use, you can write your examples once in TypeScript, and Rosetta translates them so your documentation works across all those languages. This is what powers the AWS Cloud Development Kit's multi-language documentation.

The way it works is straightforward: developers write code examples in TypeScript and mark them in their library's documentation. Rosetta reads those examples, compiles them (if possible), and then applies knowledge about how TypeScript maps to other languages to generate equivalent code in each target language. For example, a TypeScript object literal might become a class instance in Java, or a dictionary in Python. The tool can even work with examples that don't fully compile—it will parse them grammatically and do its best to translate them, though complete compilation gives better results since Rosetta can then use actual type information.

The primary users are library developers and documentation teams. If you're maintaining an open-source SDK or a reusable library and want to show examples in multiple languages without having to manually write and maintain each one, you'd use Rosetta as part of your build pipeline. You run jsii-rosetta extract to compile and translate all your examples, which creates a "tablet" file of translations that gets packaged with your library. Later, when someone generates bindings for Python or another language, those pre-computed translations are automatically inserted into the generated documentation. The tool also includes caching and parallel compilation to keep builds fast, and a separate "infuse" command that spreads single examples across multiple related classes to maximize documentation coverage.