When I was four years old, I watched a group of teenagers in colorful suits transform into dinosaur-themed superheroes and fight a space witch. In America, they called that show Mighty Morphin Power Rangers. What I didn’t know at the time was that the fight footage, suits, robots, and monsters all came from a Japanese show called Kyoryu Sentai Zyuranger.
My Copy of Kyoryu Sentai Zyuranger (恐竜戦隊ジュウレンジャー) on DVD alongside a model of Daizyuzin aka the Megazord
I didn’t know any of that back then. I just knew I wanted a transformation device more than I’d wanted anything.
Thirty years later, I bought one. I opened the box, pulled out the instruction manual, and hit the completely predictable problem with importing premium Japanese collectible toys: I couldn’t read it.
The collectible toy that started the whole thing.
For anyone who hasn’t fallen down this particular rabbit hole, tokusatsu (特撮) is the Japanese special effects genre behind Godzilla, Ultraman, Kamen Rider, Super Sentai, and eventually Power Rangers. It’s rubber suits, miniature cities, practical explosions, giant robots, and transformation devices that make a very specific part of my brain light up.
This wasn’t my first attempt at building tools for that hobby. Back in 2018, I made a fan site for transformation sequences with Python, Flask, and Contentful as a headless CMS. That project was fun, but cataloging clips is a much simpler problem than translating a 40-page toy manual without destroying the page.
Kyoryu Sentai Zyuranger (恐竜戦隊ジュウレンジャー)
The toys have gotten absurd in the best way. Bandai’s Premium Complete Selection Modification line recreates devices as full-scale collectibles with show-accurate lights, sounds, and functionality. A single belt can have more than 100 features, which is how you end up with a manual long enough to justify its own software project.
A sample of my Complete Selection Modification collection
So I built Toku Solutions, a pipeline that turns Japanese collectible toy manuals into translated, editable static sites.
Why “just translate it” didn’t work#
Google Translate’s document mode can get the words across, but it wrecks the layout. That matters more than you might think. A manual is not a novel. The relationship between a diagram, a callout, a button label, and a warning is part of the instruction.
Screenshot translation works when you need one text block. A 40-page manual turns that into hours of manual work, and by the end you still don’t have anything editable or shareable.
OCR plus translation APIs gets closer. You can extract the text, translate it, and put English back over the original page image. But once I started building that as an actual pipeline, the problem changed. It was no longer just, “Can I translate this?” It was, “Can I finish the run without throwing away everything that already worked?”
At that point I wasn’t looking for a smarter translator. I needed the run itself to survive bad calls, slow renders, and partial progress. If page seven fails after pages one through six are done, I do not want to start over because my script forgot what already happened.
What Toku Solutions builds#
Toku Solutions takes a PDF manual, extracts the text, translates it, cleans up the result, and generates a static site where the translated blocks sit on top of the original page images.
The generated site keeps the original manual visible and makes every translated block editable.
Each block is editable. You can click translated text, see the original Japanese, fix the English, adjust the bounding box, and send the change back through GitHub as a pull request. The site itself is just HTML and JSON served from a CDN, so I don’t have to maintain a custom admin app for a hobby project.
The AI is not pretending to be the final authority here. OCR misreads characters. Translation loses nuance. Technical terms get mangled. The goal is to get most of the way there and make the remaining errors easy for people to fix.
Fast enough to keep using#
A typical 20-page manual takes about 50 seconds end to end: roughly 30 seconds for parallel OCR, 5 seconds for translation, 10 seconds for AI cleanup, and 5 seconds for static site generation.
The whole run costs about 43 cents. Google Document AI is around 3 cents of that. Most of the cost is translation, and Gemini’s free tier is enough for the cleanup step. That matters because this is still, somehow, just me trying to understand a toy.
The Workflow remembers the run#
Toku Solutions runs as a parent Workflow with four Child Workflow phases: OCR, translation, site generation, and AI cleanup. Each phase is visible in the Temporal Web UI with its own Event History. Every Activity execution, retry, and result is recorded.
The CLI does not keep a second version of the truth in a database, Redis, or a message queue. It polls the Workflow every 500 milliseconds and asks for the current state.
The CLI reports progress while Temporal tracks the underlying Workflow state.
If the Worker dies, an API fails, or I deploy a new version halfway through a run, the recorded Event History is still there. When the Worker comes back, the pipeline continues from what actually happened instead of trying to reconstruct state from partial files and optimism.
OCR fans out by page#
The OCR phase is where the architecture is easiest to see. Processing a manual page by page would turn a 20-page PDF into a long wait: OCR page one, wait for the result, OCR page two, wait again, and so on.
Instead, the Workflow starts one OCR Activity per page. A 20-page manual becomes 20 simultaneous calls to Google Document AI. If page seven fails, page seven retries. The other 19 results are already in the Event History.
Fan-out OCR in the Temporal Web UI: one page per Activity, running in parallel.
Retries live in policy#
Translation is simpler, but it still fails about 2% of the time in this pipeline. The Workflow batches the extracted text blocks and sends them to Google Translate. That Activity has a Retry Policy with five attempts and exponential backoff.
I didn’t wrap every API call in custom recovery code. I declared the retry behavior where it belongs, and Temporal handles the boring part.
Heartbeats make long work visible#
Site generation has a different shape. Rendering 20 high-resolution page images takes long enough that Temporal needs to know the Worker is still alive. That Activity uses Heartbeating, which lets the Worker keep telling Temporal, “I’m still here. Don’t time me out.”
It’s a small detail until a render takes longer than expected. Then the Activity can say it is still alive instead of looking dead.
The LLM gets a box#
The AI cleanup phase is my favorite part of the system architecturally because it lets Gemini be useful without letting it run the pipeline.
Cleanup happens in three separate Activities. First, ftfy fixes encoding issues. Same input, same output. Then rule-based cleanup removes OCR junk like page numbers, stray symbols, and copyright marks. Those first two stages are deterministic.
Gemini is the third stage. It makes context-aware corrections using the product name and description, which is useful because a toy manual has weird vocabulary and repeated product-specific phrasing. But Gemini is not deterministic, and LLMs have a habit of being helpful in ways you did not ask for.
Ask for JSON and you might get JSON wrapped in markdown. Ask for a list of corrections and you might get a helpful essay. Sometimes the model just lies.
Validate the shape before trusting the output#
I use Pydantic to define the response shape the rest of the system expects: a list of removed strings, a dictionary of corrections, product names, and the other fields the pipeline needs. If Gemini returns something that does not match the schema, Pydantic throws an error.
Temporal catches that error and retries the Activity. The LLM gets another chance to return valid structured data, and I don’t have parsing and validation code scattered across the rest of the pipeline.
Keep nondeterminism out of the Workflow#
There’s also a Temporal-specific reason to keep Gemini inside an Activity. Workflow code has to be deterministic. It can’t call random or datetime.now() and expect replay to behave correctly. LLM output varies by nature, so it belongs outside the Workflow Definition.
The Workflow orchestrates the work, and the Activity handles the messy call.
That boundary also gives the pipeline a reasonable failure mode. If Gemini fails after ftfy and the rule-based cleanup have already run, the Workflow can continue with partial cleanup instead of failing the whole manual. The LLM improves the result, but it does not get to be a single point of failure.
Now I know what the buttons do#
Myself and a friend attending a the Shin Kamen Rider film premier wearing some toy manuals that I didn't understand the full feature set of at the time.
For years, collecting these devices meant living with a little uncertainty. I could press tabs, hold buttons, combine parts, and hope the manual was not explaining a mode I would never find.
Toku Solutions makes the manual usable without pretending AI translation is perfect. The original page stays visible, the English text is close enough to start from, and every block can be corrected by someone who knows the language or the toy better than the model did.
Temporal’s job in all of this is the unglamorous part: keeping the awkward middle states from turning into a restart button while OCR runs across pages, translation calls fail and retry, image rendering takes longer than expected, and LLM cleanup returns something that has to be validated before the rest of the pipeline trusts it.
Now I can stop guessing and actually use the thing I bought.
The code is open source on Temporal Code Exchange, and you can watch the full video walkthrough. If you collect similar toys and want to contribute translations, or if you want to see how Temporal Workflows handle an AI pipeline with real failure modes, check it out.