Anurag’s Read

Translating Java to Kotlin at Scale.

It shows a full pipeline for a huge language migration, including the null-safety traps and how automation avoids false confidence. Examples are Android-specific but the method transfers to any large migration.
Score
8.4
Verdict
Worth reading
Blog and date
Meta,
Original length and level
15 min, advanced
Topics
migration, kotlin, android, automation
Read the original

Context

Android development at Meta has been Kotlin-first since 2020. A mixed codebase needs two toolchains, and compiling both languages together is slow. Meta chose to convert nearly all active code and central dependencies, tens of millions of lines.

Plain converter output mostly failed to build in this codebase with custom frameworks.

Architecture

The Kotlinator first builds the code so the IDE resolves all symbols. About 50 preprocessing steps prepare Java for conversion. A headless J2K run on a remote server converts the files.

About 150 postprocessing steps fix Android specifics, null handling and style. Linters run with autofixes. A last phase parses compiler errors and applies fixes.

A daily job builds diffs, picks reviewers, checks tests and ships after human approval.

Mechanisms

M1

Headless J2K

An IntelliJ plugin starts the converter directly through an application starter class. It runs on a remote machine, so it does not block local IDEs. It converts many files in one batch and allows slow build-and-fix steps.

M2

PSI-based tooling

Custom steps use JetBrains PSI libraries, not compiler plugins. They work on code that does not build. When type data from third-party code is missing, a step stops instead of guessing.

M3

Null-safety handling

The compiler adds runtime null checks at the Java and Kotlin boundary. When context is unclear, the tool makes parameters and return types more nullable. Added not-null assertions get close review. Over a dozen codemods find missing nullable markers, and a compiler plugin collects runtime data on null values.

M4

Build-error fixes

The pipeline reads compiler messages and applies the fix a person would apply. Examples are adding an import or inserting an assertion. This avoids copying complex Kotlin compiler logic.

Design decisions

No.ChoseInstead ofWhy
D1Convert nearly all active codeOnly new code in Kotlin, or only the most important filesA mixed codebase keeps two toolchains and slows builds.
D2Run J2K headless on a serverRun it in a test-like IDE environmentThis design avoids blocking developers and supports batches.
D3Fix compiler errors after conversionRebuild compiler logic in postprocessingReading errors is simpler and works like a human fix.

Key numbers

  • About 10 million Java lines to convert.
  • About 100,000 manual clicks avoided.
  • About 50 preprocessing and 150 postprocessing steps.
  • About 30 minutes per remote conversion.
  • More than 40,000 conversions shipped.

Failures and limits

  • Static null analysis cannot reach full coverage, so null-safe Java can still throw.
  • Kotlin rejects some property dereferences, so extra not-null assertions appear.
  • Thousands of conversions stay blocked for full automation.
  • Some fixes depend on custom symbol resolution that is hard to open-source.

Lessons you can use

  • Measure the manual cost first, and automate when it reaches tens of thousands of steps.
  • Make tools stop when type data is missing instead of guessing.
  • Use compiler errors as input to automatic fixes.
  • Work with the tool vendor when a black box limits you.

Glossary

J2KThe IntelliJ Java to Kotlin converter.
PSIJetBrains syntax tree library that works on code that does not build.
CodemodA script that edits code across many files.