jsii-rosetta

Common errors

• Error: Cannot find module 'jsii-rosetta' or its corresponding type declarations.

  cause The `jsii-rosetta` package is not installed, or there's an issue with module resolution in your build system (e.g., TypeScript configuration).
  fix Run `npm install jsii-rosetta` or `yarn add jsii-rosetta`. Verify your `tsconfig.json` includes `node_modules` in its `typeRoots` or `moduleResolution` settings.

• TypeError: rosetta.translateTypeScript is not a function

  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.
  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.

• The Rosetta kernel failed to initialize. Make sure you have a compatible jsii-runtime installed.

  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.
  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.

• TypeScript diagnostics: Cannot find name 'cdk' (or similar for other `jsii` types)

  cause The `jsii-rosetta` instance cannot resolve types from `jsii`-generated libraries (like `aws-cdk-lib`) that are used in the snippet being translated.
  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.

Warnings

• breaking `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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install jsii-rosetta npm
• yarn add jsii-rosetta yarn
• pnpm add jsii-rosetta pnpm

Imports

• Rosetta
  wrong:

  const Rosetta = require('jsii-rosetta').Rosetta;

  correct:

  import { Rosetta } from 'jsii-rosetta';

  The primary class for initiating and managing code translations. Always prefer ESM imports for modern Node.js and TypeScript environments.
• TargetLanguage
  wrong:

  import { LANGUAGES } from 'jsii-rosetta';

  correct:

  import { TargetLanguage } from 'jsii-rosetta';

  An enum defining the available target languages for translation, such as PYTHON, JAVA, CSHARP, and GO.
• renderTypeScriptSnippet

  import { renderTypeScriptSnippet } from 'jsii-rosetta';

  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.

Quickstart

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.

import { Rosetta, TargetLanguage } from 'jsii-rosetta';

async function translateCode() {
  const rosetta = new Rosetta();
  const tsSnippet = `
    import * as cdk from 'aws-cdk-lib';
    import * as ec2 from 'aws-cdk-lib/aws-ec2';

    const app = new cdk.App();
    const stack = new cdk.Stack(app, 'MyStack');

    new ec2.Vpc(stack, 'MyVpc', {
      maxAzs: 2,
      natGateways: 1,
    });

    app.synth();
  `;

  // Translate to Python
  const pythonTranslation = await rosetta.translateTypeScript(tsSnippet, {
    language: TargetLanguage.PYTHON,
    trimLeadingEmptyLines: true,
    indentation: 4,
  });

  if (pythonTranslation.translation) {
    console.log('Python Code:\n', pythonTranslation.translation.source);
  } else if (pythonTranslation.didFail) {
    console.error('Python translation failed:', pythonTranslation.failure);
  }

  // Translate to Java
  const javaTranslation = await rosetta.translateTypeScript(tsSnippet, {
    language: TargetLanguage.JAVA,
    trimLeadingEmptyLines: true,
    indentation: 4,
  });

  if (javaTranslation.translation) {
    console.log('\nJava Code:\n', javaTranslation.translation.source);
  } else if (javaTranslation.didFail) {
    console.error('Java translation failed:', javaTranslation.failure);
  }
}

translateCode().catch(console.error);