{"id":15660,"library":"jsii-rosetta","title":"jsii-rosetta","description":"The `jsii-rosetta` library, currently at version 5.9.39, is an essential tool within the `jsii` ecosystem, developed by AWS. Its core purpose is to translate code snippets written in one `jsii`-supported language (primarily TypeScript) into other target languages such as Python, Java, C#, and Go. This functionality is crucial for projects like the AWS Cloud Development Kit (CDK), enabling documentation to display examples across various programming languages from a single source. `jsii-rosetta` maintains a rapid and continuous release cadence, frequently updating its internal `jsii` and TypeScript dependencies to ensure compatibility and leverage the latest `jsii` features. Its key differentiator is its specialized focus on `jsii`-compliant code translation, providing robust tools for syntax analysis, type resolution, and idiomatic translation across multiple language runtimes.","status":"active","version":"5.9.39","language":"javascript","source_language":"en","source_url":"https://github.com/aws/jsii-rosetta","tags":["javascript","typescript"],"install":[{"cmd":"npm install jsii-rosetta","lang":"bash","label":"npm"},{"cmd":"yarn add jsii-rosetta","lang":"bash","label":"yarn"},{"cmd":"pnpm add jsii-rosetta","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"`jsii-rosetta` is an integral part of the `jsii` ecosystem, relying heavily on `jsii` for understanding type systems, metadata, and runtime conventions during code translation.","package":"jsii","optional":false},{"reason":"TypeScript is the primary source language for `jsii` constructs and `jsii-rosetta` utilizes TypeScript's compiler API for parsing, type checking, and detailed code analysis before translation.","package":"typescript","optional":false}],"imports":[{"note":"The primary class for initiating and managing code translations. Always prefer ESM imports for modern Node.js and TypeScript environments.","wrong":"const Rosetta = require('jsii-rosetta').Rosetta;","symbol":"Rosetta","correct":"import { Rosetta } from 'jsii-rosetta';"},{"note":"An enum defining the available target languages for translation, such as PYTHON, JAVA, CSHARP, and GO.","wrong":"import { LANGUAGES } from 'jsii-rosetta';","symbol":"TargetLanguage","correct":"import { TargetLanguage } from 'jsii-rosetta';"},{"note":"A utility function that can directly render a TypeScript snippet into a target language, often used for simpler, direct translations without instantiating the full `Rosetta` class.","symbol":"renderTypeScriptSnippet","correct":"import { renderTypeScriptSnippet } from 'jsii-rosetta';"}],"quickstart":{"code":"import { Rosetta, TargetLanguage } from 'jsii-rosetta';\n\nasync function translateCode() {\n  const rosetta = new Rosetta();\n  const tsSnippet = `\n    import * as cdk from 'aws-cdk-lib';\n    import * as ec2 from 'aws-cdk-lib/aws-ec2';\n\n    const app = new cdk.App();\n    const stack = new cdk.Stack(app, 'MyStack');\n\n    new ec2.Vpc(stack, 'MyVpc', {\n      maxAzs: 2,\n      natGateways: 1,\n    });\n\n    app.synth();\n  `;\n\n  // Translate to Python\n  const pythonTranslation = await rosetta.translateTypeScript(tsSnippet, {\n    language: TargetLanguage.PYTHON,\n    trimLeadingEmptyLines: true,\n    indentation: 4,\n  });\n\n  if (pythonTranslation.translation) {\n    console.log('Python Code:\\n', pythonTranslation.translation.source);\n  } else if (pythonTranslation.didFail) {\n    console.error('Python translation failed:', pythonTranslation.failure);\n  }\n\n  // Translate to Java\n  const javaTranslation = await rosetta.translateTypeScript(tsSnippet, {\n    language: TargetLanguage.JAVA,\n    trimLeadingEmptyLines: true,\n    indentation: 4,\n  });\n\n  if (javaTranslation.translation) {\n    console.log('\\nJava Code:\\n', javaTranslation.translation.source);\n  } else if (javaTranslation.didFail) {\n    console.error('Java translation failed:', javaTranslation.failure);\n  }\n}\n\ntranslateCode().catch(console.error);\n","lang":"typescript","description":"This example demonstrates how to initialize the `Rosetta` translator and translate a TypeScript AWS CDK code snippet into Python and Java, handling potential translation failures."},"warnings":[{"fix":"Always ensure your `jsii-rosetta` version is compatible with your project's `jsii` and `typescript` versions. Refer to the `jsii-rosetta` release notes and `jsii` compatibility matrix.","message":"`jsii-rosetta` is tightly coupled with its internal `jsii` and TypeScript dependencies. Upgrading `jsii` in your project without also updating `jsii-rosetta` can lead to build failures or incorrect translations due to API mismatches.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure your Node.js environment meets or exceeds the specified minimum version (currently `>= 20.16.0`). Use a Node.js version manager like `nvm` to easily switch versions.","message":"The `engines` field in `package.json` specifies a minimum Node.js version. Using an older Node.js version will result in errors and prevent `jsii-rosetta` from functioning correctly.","severity":"gotcha","affected_versions":">=5.0.0"},{"fix":"Design `jsii` constructs with clarity and strong typing. Test translations for complex snippets. Simplify TypeScript patterns where direct translation might be ambiguous or non-idiomatic in target languages.","message":"While `jsii-rosetta` aims for accurate translation, highly complex or non-idiomatic TypeScript code (e.g., extensive use of `any`, advanced generics without clear type boundaries, or intricate conditional types) may result in less accurate or failing translations in target languages.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Install all necessary `jsii` packages (e.g., `aws-cdk-lib`) as `devDependencies` or `dependencies` in your project. If running in a separate context, ensure the `node_modules` are properly resolved or paths configured.","message":"When running `jsii-rosetta` programmatically, ensure all `jsii` dependencies required by the snippets being translated are correctly installed and available in the environment where `jsii-rosetta` executes. Missing dependencies will cause type resolution failures during translation.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Run `npm install jsii-rosetta` or `yarn add jsii-rosetta`. Verify your `tsconfig.json` includes `node_modules` in its `typeRoots` or `moduleResolution` settings.","cause":"The `jsii-rosetta` package is not installed, or there's an issue with module resolution in your build system (e.g., TypeScript configuration).","error":"Error: Cannot find module 'jsii-rosetta' or its corresponding type declarations."},{"fix":"Ensure you are using `import { Rosetta } from 'jsii-rosetta';` and instantiate it with `new Rosetta()`. Check `jsii-rosetta` documentation for API changes if using an older version.","cause":"This usually indicates that `Rosetta` was not correctly imported or instantiated, or an outdated version of `jsii-rosetta` is being used where the API might differ.","error":"TypeError: rosetta.translateTypeScript is not a function"},{"fix":"Ensure your Node.js version meets the `jsii-rosetta` requirements (e.g., `>= 20.16.0`). Reinstall `jsii-rosetta` to ensure all its peer dependencies, including the `jsii-runtime`, are correctly linked.","cause":"The internal `jsii` runtime that `jsii-rosetta` depends on could not be found or is incompatible with the installed `jsii-rosetta` version, often due to Node.js version or `jsii` package mismatches.","error":"The Rosetta kernel failed to initialize. Make sure you have a compatible jsii-runtime installed."},{"fix":"Ensure that the `jsii` packages referenced in your code snippets are installed in your project's `node_modules` (e.g., `npm install aws-cdk-lib`). If running programmatically, you might need to specify a `projectRoot` in `Rosetta`'s options for proper module resolution.","cause":"The `jsii-rosetta` instance cannot resolve types from `jsii`-generated libraries (like `aws-cdk-lib`) that are used in the snippet being translated.","error":"TypeScript diagnostics: Cannot find name 'cdk' (or similar for other `jsii` types)"}],"ecosystem":"npm"}