Multilingual Documentation with Claire Froelich

Episode Description

Claire Froelich shares her journey from Japanese interpreter to software developer and her work localizing RedwoodJS tutorial documentation.

Episode Summary

In this episode of FSJam, Claire Froelich discusses her unconventional path into software development, starting as an interpreter and translator in Japan before transitioning through a Ruby on Rails boot camp into the tech world. The conversation traces how her language background uniquely positioned her to lead the internationalization and localization effort for the RedwoodJS tutorial documentation. Claire walks through the extensive research phase she undertook, testing seventeen different repository setups and tools—from building custom static site generators to evaluating frameworks like Eleventy, VuePress, and Docusaurus—before settling on Docusaurus 2 paired with Crowdin as a localization manager. She explains the key challenges: keeping translations in sync with a living document, crowdsourcing volunteer translators, and reducing noise on the main RedwoodJS repository. The discussion also touches on the role of machine translation, where Claire acknowledges its impressive progress while arguing that the RedwoodJS tutorial's distinctive voice and humor require human translators, ideally native speakers of the target language. The episode closes with a look at current needs, including French translation completion and community-building efforts to sustain the localization project long-term.

Chapters

00:00:00 - Introduction and Claire's Background

Anthony welcomes Claire Froelich to FSJam and asks about her background. Claire introduces herself as a software developer at Midtbyen whose side passion is helping the RedwoodJS team internationalize their tutorial documentation. She shares that she has a liberal arts background, having started as an electrical engineering student before pivoting to study Japanese and Spanish.

The conversation moves into Claire's time in Japan, where she worked as an interpreter and translator. She also studied jazz piano under a mentor in Japan, which leads to a fun tangent about Anthony's experience playing stand-up bass as a music major. The two bond over their shared love of jazz and its improvisational nature, drawing parallels to podcasting itself.

00:04:45 - From Interpreting to Coding

Claire describes her transition from language work to software development. While working at Sapporo City Hall, she built small JavaScript tools to help coworkers with address translations, planting the first seeds of her interest in coding. She then moved to Amazon Japan as an internal interpreter, where being embedded in a major tech company inspired her to start building things herself.

After leaving Japan in 2018, Claire traveled through South America before landing in Canada, where she enrolled in a Ruby on Rails boot camp. She and Anthony compare their boot camp experiences—hers was back-end heavy with Rails, while his at Lambda School was heavily focused on React front-end development. They discuss how their complementary gaps made RedwoodJS an ideal framework for both of them, since it bridges front-end and back-end concerns.

00:10:00 - Getting Involved with RedwoodJS

Claire explains how she discovered RedwoodJS through a talk Rob Cameron gave at Mintbean, where she asked about translating the documentation. David Price later reached out and brought her on board. Anthony recalls Claire's first community contribution—a forum post about setting up Postgres locally—and draws parallels to other community members who gravitated toward database challenges as entry points.

The conversation shifts to comparing ActiveRecord and Prisma as ORMs. Claire recounts her frustrating early experience with Prisma 1, where writing both Prisma schemas and GraphQL schemas felt redundant, but notes that Prisma 2 within RedwoodJS has been a much more pleasant experience. This sets up the deeper discussion about the localization project that follows.

00:13:19 - Planning the Localization Effort

Claire details her approach to localizing the RedwoodJS tutorial, beginning with Anthony's observation about the extraordinarily long forum post that documented the research process. She emphasizes that planning is crucial and advises anyone considering localization to first define goals, identify target audiences, and understand the nature of the content being translated before jumping into infrastructure decisions.

The team chose French as the first translation language based on community volunteer availability, which turned out to be a sensible choice given that France ranks third among tutorial website visitors. Claire and Anthony discuss the additional complexity that comes with non-Latin character sets and right-to-left languages like Arabic, noting that these considerations will need to be addressed as the project scales beyond its current Latin-alphabet languages.

00:20:07 - Technical Decisions and Framework Exploration

Claire outlines her three core requirements: keeping translations in sync with the evolving English source, enabling easy crowdsourced contributions, and reducing noise on the main RedwoodJS repository. She explains why modifying the existing site built with Cameron JS proved impractical, and how she explored using GitHub Actions to sync a separate translation repo with the main docs before ultimately deciding to build a standalone subdomain for tutorials.

The exploration phase was extensive, involving seventeen different repository experiments. Claire tried building a custom static site generator, evaluated Eleventy, considered VuePress for its built-in multilingual support, and tested Docusaurus 1 before discovering that Docusaurus 2 had an internationalization feature under active development. This long journey taught her the value of leveraging existing tools rather than reinventing the wheel.

00:29:04 - Docusaurus 2 and Crowdin

Claire describes how she found the Docusaurus 2 internationalization effort led by Sebastien Lorber and decided to build on it despite the feature not yet being officially released. She explains the distinction between internationalization (the infrastructure for serving multilingual content) and the localization tool Crowdin, which replaced her earlier pick of GitLocalize due to its more robust feature set and free availability for open source projects.

The team built the entire Redwood tutorial localization without official Docusaurus documentation, relying instead on source code reading and direct communication with Docusaurus developers. Claire also observed the Jest team migrating their docs to Docusaurus 2, which provided additional reference points. Anthony and Claire discuss the interesting dynamics of Facebook-backed open source projects versus truly community-driven ones like RedwoodJS, noting the tension between open source visibility and corporate control over project direction.

00:37:27 - Machine Translation vs. Human Translation

Anthony asks about the role of automated translation, prompting Claire to reflect on how machine translation has evolved dramatically over her career. She recalls a humbling moment when Google Translate produced a better translation than she could, but argues that the RedwoodJS tutorial—with its distinctive voice, humor, and idioms—requires human translators who are native or near-native speakers of the target language.

Claire explains how Crowdin incorporates machine translation as a translation aid, offering suggested translations based on aggregated data from other translators. The conversation broadens into the linguistics of translation, touching on word vectors in natural language processing and Steven Pinker's writings on language and cognition. Both hosts express fascination with how far machine translation has come while acknowledging its persistent limitations with context-heavy languages like Japanese.

00:46:20 - Current Status and Future Plans

Claire provides an update on the project's current state: the Learn RedwoodJS subdomain is live with a French translation of tutorial part one, and a new part two has been released that still needs translating. She invites French speakers and anyone interested in other languages to get involved, noting that the onboarding process for new translators is straightforward through GitHub issues.

Looking ahead, Claire identifies community building as her next priority, drawing inspiration from how TypeScript and Gatsby manage localization communities through dedicated Discord channels for each language. She also highlights the need to better recognize translation contributors—potentially through badge systems or inclusion on the official contributors list—to incentivize ongoing participation and make translators feel valued as true contributors to the RedwoodJS project.

Transcript

00:00:00 - Claire Froelich

I don't think I pronounce it right, but it's Freilich.

00:00:13 - Anthony Campolo

Oh, Freilich. So not Froelich. Freilich.

00:00:15 - Claire Froelich

I don't know. If you ask a German person, they'll probably correct me, so I wouldn't trust me.

00:00:19 - Anthony Campolo

Because I feel like most people probably say Froelich. I don't know, maybe that's just in my brain. I always say Froelich.

00:00:24 - Claire Froelich

Oh, totally. That's what I get at the grocery store.

00:00:28 - Anthony Campolo

All right. Three, two, one. Claire Froelich, welcome to FSJam.

00:00:35 - Claire Froelich

Hey, Anthony.

00:00:36 - Anthony Campolo

Super great to have you here. You're someone who has been kicking around the Redwood and FSJam world for a while, probably longer than people realize. But before we get deeper into that whole history, tell our listeners who you are and what you do.

00:00:52 - Claire Froelich

Yeah. I never imagined I'd actually be talking to you on FSJam. I'm usually talking to you on Slack or Discord.

My name is Claire Freilich, and I am a software developer at a startup called Midtbyen. That's my day job, but on the side I have a lot of fun with the Redwood team, and I've been helping them internationalize and localize their tutorial documentation.

00:01:13 - Anthony Campolo

It's been awesome seeing you take off with this project because the scope and the scale of it are huge. I think people have a hard time wrapping their minds around it. People realize it's complicated, with lots of languages and a lot that goes along with it. But until you really get your hands on it and start to see what the challenges are, it can be hard to grasp.

It's cool because it seems to really gel with your background and what you did before programming, because you're someone who got into this in your 20s, like me. I'd be curious to hear what you were doing before you got into coding and how you started to make that transition.

00:01:51 - Claire Froelich

Totally. I think I'm very similar to you in that I have a liberal arts background. Before coming to the dark side of coding, I was an interpreter and translator in Japan. These have been two undercurrent passions in my life. I've always been very interested in tech, but I've also been pulled toward language. That's a decision I had to make in university, and I couldn't quite make it. I started out as an electrical engineer and then quickly veered into Japanese and Spanish as my field of study.

00:02:22 - Anthony Campolo

What school did you go to?

00:02:23 - Claire Froelich

I went to lots of schools, but the first one I went to was Washington State. Then that got too expensive, so I transferred to the University of Montana. Then the year after that, I did a year in Tokyo and went back to graduate in Montana.

00:02:38 - Anthony Campolo

It's a good mix, and I once saw a video of you playing piano with a jazz trio in Japan. How exactly did that happen?

00:02:48 - Claire Froelich

Yeah, well, like you, I also have an interest in music, and I played saxophone and was in jazz bands for a long time when I was back in the States. While I was in Japan, the home of Yamaha and all of these amazing piano makers, I went to the Yamaha school and met this amazing older, like 60-year-old woman who became my piano mentor. She was a jazz musician and let me play with some of the people she knows in the world. I was very fortunate, very underskilled, but very fortunate to get to play with them.

00:03:19 - Anthony Campolo

Jazz is always my favorite kind of music to play. I played almost every genre there is, and I enjoyed all of them in their own ways. But playing jazz, because of the improvisational nature of it, was totally different from any other medium, except for a couple rock bands that got pretty close, but not many.

00:03:38 - Claire Froelich

Did you play stand-up bass? Because I see a profile picture of you with a large bass-looking thing.

00:03:44 - Anthony Campolo

Yeah, I played stand-up bass. I played electric bass. I started on the stand-up because when you major in music, there are lots of preconceived notions of what goes along with that. That has lots to do with the classical tradition. So if I was going to major in instrumental music education, I had to play the upright. They literally would not let me major on the electric bass. If I'd done jazz, though, I would have been able to do the electric bass. So it was like this weird kind of culture clash thing in the university. But it was good because otherwise I would have never learned to play it at all. So it was really fun.

It's such a hard instrument, though, versus the electric. You get a lot more control because you're plugged in. If you want more sound, you just turn up. You can't do that with the stand-up.

00:04:32 - Claire Froelich

And you have no frets, I think, right?

00:04:34 - Anthony Campolo

Yeah, that's true. That's probably the worst part. You have to actually know what the note is supposed to be.

00:04:39 - Claire Froelich

Well, it's funny now you're doing podcasting, which is kind of like jazz. You're improvising.

00:04:45 - Anthony Campolo

That's right. Cool. How'd you get into coding? In terms of the Mintbean stuff and the hackathons, how did all that start to come together?

00:04:54 - Claire Froelich

There's definitely a 180 there, going from interpreting in Japan to this. Like I said, I've always been very interested in tech, or tech-adjacent. So even when I was an interpreter, I was working at City Hall in a city called Sapporo. It's like the most backward tech situation you could be in because Japan is a very technical place, but when you're working for the government in Japan, you're working in the 70s. Fax machines were still a legitimate way to communicate. We were working in Windows 7 on the computers.

Even though that was the technical environment I was in, tech still came into play. I built little tools in JavaScript to help my coworkers do this kind of menial translation they always had to do for addresses. There was a very specific way that you had to translate addresses, so I made this little regex program to help them do that without me. As far as I know, after I left they still kept using it, so that was a success.

[00:05:49] After working at City Hall, I moved to Amazon Japan as an internal interpreter and translator there. I wasn't working as a software engineer, but I was working in this big tech company and being like a fly on the wall at every level of the company. I was working in a support call center, but I was interpreting for the management, so I'd be on calls with upper management, even calls with the president of Amazon Japan.

It was a very interesting position to be in as somebody that didn't study tech formally but got to be in on all these conversations about big tech and big business. That got me thinking: I enjoy translation and interpreting, and there is a creative element to it. It's not just taking somebody's words and literally translating them. There's a lot of analytical and summarization skills that come into play as well. But I was seeing these people building things, and I was like, I want to do that.

[00:06:44] You know, so far I've been taking a lot of people's ideas and communicating to other people. I wanted to try and push myself to actually build things. That's how the little seed was planted: maybe I should transition out of this.

I ended up leaving Japan in 2018 and wanted to take the opportunity of my youth to travel. So I was traveling in South America, just doing labor to pay my way, and I ended up getting my passport stolen along the way. So I ended up landing in Canada for a little while for other reasons. It was when I was in Canada that I found a boot camp, and I thought, this is my opportunity. I have no job that I'm obligated to right now. I have a lot of time to devote to this, and now is my time to finally dive into tech. So I did that, and I graduated and got my first freelancing gig, building a website with a partner, and it paid for the camp.

00:07:43 - Anthony Campolo

I'm curious, before you get into that, what was your curriculum for your boot camp and the tech stack you studied?

00:07:49 - Claire Froelich

Yeah, it was a Ruby on Rails boot camp, so Rob Cameron would be happy to hear that. It was a three-month boot camp. You go in knowing nothing; you come out knowing MVC software structure and having built two applications that are functional.

00:08:05 - Anthony Campolo

Yeah, I would have liked to have gotten that out of boot camp.

00:08:08 - Claire Froelich

How was your education, by the way? Because you switched as well.

00:08:13 - Anthony Campolo

Oh, it's complicated.

00:08:17 - Claire Froelich

Are you self-taught?

00:08:18 - Anthony Campolo

No, I did a boot camp. I did Lambda School, which is one of the most well-known, well-funded boot camps there is. It's quite controversial, actually, but I got a lot out of it. I would recommend it to certain people in specific situations, mostly people who can't afford to put money down at the beginning for a boot camp.

I got a lot out of it, really learning how to work with React, because it was very front-end heavy. React was such a big focus, which is why I find it so interesting. I always ask this question of people who went to boot camps: what tech did they actually study? It's a wide range of things. I definitely feel like I got the most front-end-heavy boot camp experience of almost anyone I know. Most people either did almost entirely Rails or they did Python, Django, or Flask with half that and half front end. Whereas mine was like 80% front end and like 20% back end.

[00:09:10] So Redwood was made for me. Redwood was made for people who got a lot of React experience and have no idea how to work with the back end. It ended up being a kind of blessing in disguise, and that set me up really well to contribute and thrive in Redwood, even though at the time I was like, this isn't a full-stack curriculum. The program was literally called Full Stack, and I thought that was a misnomer.

00:09:37 - Claire Froelich

I think I was the opposite puzzle piece to you because ours was very back-end heavy and we didn't even touch React or anything. It was just vanilla JavaScript. Coming out of the camp, I was very interested to study React, and that was what I dove into. Like you said, Redwood is built for people that do front end because it takes care of the back end. For me it was a good playground to play more around with the front end.

00:10:00 - Anthony Campolo

So you were getting into something right before I interrupted you?

00:10:03 - Claire Froelich

Yeah. Where were we? I think I was doing a freelance project. I got my first freelance project, which helped me fund myself a little bit longer to keep self-studying.

I was doing these hackathons at a little startup. They were doing this weekly hackathon. The place was called Midtbyen, and it was a community of people kind of like me: finished boot camp, finished education, and haven't landed that first job yet. So just kind of building portfolio, building confidence, building skills.

I got recognized for some of my hackathon submissions there, and they ended up hiring me. That's where I've been since, I guess it was July last year, almost a year.

00:10:43 - Anthony Campolo

And if people want to know more, they can listen to episode three with Monarch.

00:10:48 - Claire Froelich

Yes. My dear boss has been on your show.

00:10:51 - Anthony Campolo

He's the second guest after David, actually.

00:10:54 - Claire Froelich

Yeah. Cool.

00:10:55 - Anthony Campolo

Awesome. You started in July, and then the first thing I ever saw you do in the Redwood world was you wrote a blog post, or not a blog post, a forum post the next month about setting up Postgres locally, I think is what it was. It was Postgres for noobs.

00:11:12 - Claire Froelich

You were a great forum stalker. Yeah, that was me getting acquainted with Redwood and trying to figure out how to set up Postgres locally.

00:11:18 - Anthony Campolo

Yeah, and that's great because that's like Kim's story. She did it with Azure Postgres. Right now Lucia at Stetson is getting spun up with MySQL. So I find some interesting parallels: what people gravitate towards and what they take as a project to be like, this is the thing I want to do. This is the thing I know I don't know how to do, and I know it's complicated, but it's also important and consequential and could be a cool thing to get my hands on.

That's also what appealed to you about databases, even though I got the super front-end heavy education. I've always been really fascinated by databases, even way before I got into web. When you did Rails, what database were you using?

00:12:02 - Claire Froelich

We were using Postgres, but with Rails you have that whole ActiveRecord help, so it wasn't as painful to set up.

00:12:10 - Anthony Campolo

Yeah. So then how does working with ActiveRecord compare to working with Prisma?

00:12:15 - Claire Froelich

That's a good question. A lot of people say this about Rails, about how comfy and cozy it is. I have to agree; it's very intuitive.

Prisma, I have a rough history with because I started Prisma back when it was Prisma 1, and I was doing one of those Wes Bos tutorials. He does an advanced React course with Prisma 1, and I just felt this is so redundant. I feel like I'm writing the same thing twice. You're writing your Prisma schemas and you're writing your GraphQL schema, and I felt like I was doing the same thing. When you're just learning, you're getting really confused. What's the difference? Am I in Prisma land? Am I in GraphQL land?

Now that it's Prisma 2, and now that I know more about GraphQL, I'm finding Prisma a joy to work with on this. I'm making a side project right now in Redwood, and first of all, it took like one line to set up my Postgres database.

[00:13:11] And second of all, Prisma makes it really easy to interact with that database. I can't complain. The conventions are there.

00:13:19 - Anthony Campolo

And how did you first hear about Redwood?

00:13:21 - Claire Froelich

Actually through Mintbean, because I believe it was Rob Cameron that came and did a little pitch for Redwood at Mintbean. It was maybe like an ask me anything or something.

This is actually how I got involved with Redwood, because I think during that talk in the chat section I asked, do you guys have any thoughts about translating your documentation? I was just so excited about this project and I wanted to get involved in some way, but I was still kind of a freshman in the tech world, and I didn't know if I could contribute in a meaningful way to the platform itself. So I thought, well, I have this translation experience. Maybe that's some way I could get involved. And yeah, David Price ended up reaching out to me and taking me up on that a little while later.

00:14:10 - Anthony Campolo

Awesome. Yeah. Let's get into translating the docs now, because I remember this very vividly when you were brought on. I was very excited to hear that someone wanted to come in and do it.

Because, funny enough, I have a long history and interest in translation, not in the practical sense of what you were doing, but more in the theory of how you think about translation. What you were saying about how it's slightly creative and it's not as straightforward as most people think. You're not just replacing words from one language with words from another. There's a lot that's wrapped up in that.

I once went into this huge rabbit hole of the history of translation, going all the way back to the confusion of tongues story, which most people think of the Tower of Babel, but actually goes back to Mesopotamia like 1500 years before that. Then you have a lot of Greek thought around it, like what does a word actually mean? Does it represent something real or not?

Then you had this trend in the 1600s where philosophers wanted to create a universal language to represent all ideas, and that eventually morphed into Esperanto and that kind of stuff. I remember researching this and finding it so fascinating. So it was such a deep, dense, long-lived historical problem. And so I thought it was cool that you wanted to do it.

And then once we got into it, like we'll link to this in the show notes, this is literally the longest forum post that's ever been on Redwood by quite a large margin, probably at least twice as long as the next longest one. So how did you approach it when you started?

00:15:55 - Claire Froelich

Yes. Speaking of language being a problem, there was a lot of language thrown around.

There was a learning process. I do remember you were the first person that reached out and was really excited about this, and that kind of gave me a little energy to see, like, oh, there's somebody else in the community that's also interested in seeing this come to fruition.

To be honest, I was given totally free rein because it was a little side endeavor for the Redwood tutorial. In hindsight, I wish there had been more planning. I think I went in a little bit too early to dive into the infrastructure and the localization aspect of it. Probably before that step, anybody that's thinking of localizing their website right now should think from the outset: what are your goals for localizing, and who is your audience?

What languages are you going to target? What kinds of needs does your website have? Because there are different types of websites. In the case of the tutorial, we have lots of markdown documents, long text that needs to preserve its format. But maybe, for example, another website that I've translated recently was my own children's book website, which does not have lots of markdown text. It has very little text because it's aimed at children. The localization approach for that website is radically different than this.

So first of all, just know the beast and know the goal would be my advice to my past self.

We ended up knowing what language to go for. After a long discussion in that forum, I'm sure you've seen we were doing all this statistical analysis of what the most popular language might be or what our users might be familiar with.

We ended up just going with a community member that spoke French and was willing to translate the 18,000-word tutorial. So we did it on an availability basis for the first translation, which was French. And you know what? That's not a bad first language to go for because a lot of the world speaks French.

It's a chicken-or-egg question because I just checked on Netlify what the highest viewers of our tutorial website are, and you have the US, the UK, and then France is the third one. I was like, I wonder if that's because of the French translation or if it just happens to be that a lot of developers are in France. I don't know. So long story short, planning is important.

00:18:50 - Anthony Campolo

I thought it was good to just pick a language to go with it. That's a good approach. The thing, though, you've got to keep in mind is if you want to plan for all the languages, there's a much wider character set you have to deal with versus like French. It's very similar to English in the sense of it's pretty much the same alphabet. Is it? Actually, I don't know that for sure.

00:19:17 - Claire Froelich

There's some extras, and actually with French in terms of character sets, there are these funny cases where sometimes you have to put spaces before punctuation, and that actually comes into play with HTML. Sometimes you have to use that  . So far we haven't run into that problem.

00:19:38 - Anthony Campolo

It's a much bigger stretch to go to Russian or Japanese or any of those. Those are entirely different character sets.

00:19:46 - Claire Froelich

That's definitely something you have to keep in mind, especially if you're going to do a language that reads right to left, like Arabic. That's going to change how your UI thought process works. So far, we only have these Latin alphabet languages, and that will definitely need to be thought through.

But in terms of how we arrived at the current setup, is that what you're aiming after?

00:20:07 - Anthony Campolo

Yeah. So let's get into the tech decisions that went into it. Because one funny thing that you did is, I think what the project really needed is it just needed a long research phase, essentially.

00:20:19 - Claire Froelich

Yeah.

00:20:19 - Anthony Campolo

I thought you did a really good job of this because you basically sussed out: can we do this with the current website? Can I kind of build my own solution to do this? And then what solution actually exists that's going to fill this need? How did you first figure out that our current setup wasn't going to quite work, that it was going to be more difficult than it was worth?

00:20:40 - Claire Froelich

Coming into this, there were three requirements I had on my mind. One was this is a living document. These tutorials are being updated constantly. How do we prevent staleness between languages?

The other requirement was we're going to need to crowdsource translations, so we aren't going to pay people. This is an open source project, so how can we make it super easy for anybody in the community just to jump into the project and know how to get started and build a mechanism that's self-sustaining?

The third one was, how can we reduce noise on the RedwoodJS.com repo? Because there's already a lot of PRs flying into it for the actual docs for Redwood. It's also the hub for news. It's the hub for getting those free stickers. It's everything. Adding translation pull requests into that mix was just going to create a lot of noise, I felt. I was wondering, is there a way we can abstract that and remove it from the .com repo?

[00:21:34] So those were my three goals, and the current RedwoodJS website is built with this beautiful framework called Cameron JS, which is a static site.

00:21:43 - Anthony Campolo

Although it's not a framework, he will say. Actually, now he's rolled back the framework part.

00:21:49 - Claire Froelich

What does he call it?

00:21:51 - Anthony Campolo

He's like, it's just like HTML and stuff.

00:21:55 - Claire Froelich

Sure. Well, anyway, it is a system for building static websites, and it's set up really beautifully right now. I felt like I didn't want to interrupt it.

So I actually have a folder open. Like you said, I went through all these iterations, and I'm counting 17 repos I built in here, trying out different solutions.

Like you said, I gave up on doing it on Redwood.com pretty quickly just because, well, I'll say this: there's kind of two aspects to translating a website. You have your internationalization, or i18n, and you have localization, or l10n. Much easier to say localization out loud. Internationalization is the plumbing or the architecture side of making websites multilingual. Localization is the actual content, translating the actual words that you're going to read. So you can think of it kind of like plumbing and sewage, which is not really beautiful. Maybe like honeycombs and honey, I guess, in terms of the plumbing.

[00:22:58] It was going to be difficult on the .com website to add multilingual pages because it's set up to build beautifully and auto-create the sidebars and everything based on this kind of single source of English truth at this time. To try and manipulate that to build for different languages was going to take a lot of change, which could have been done. But I thought maybe there's a better way to do this and also achieve those other goals, which were like reducing noise on the repo and building this self-sustaining translator ecosystem.

So I started looking into, okay, maybe we can have a separate repo for the localized content, like the translated content, and during the build process on dotcom, maybe go fetch those and pull them into the website. This way, all of the conversation and the activity revolving around translation would be in a totally different repo and not pollute the dotcom space. So I was playing around with GitHub Actions and thinking, how can we prevent this remote repo from getting stale relative to the English docs?

[00:24:03] Turns out it's not super easy to make pull requests across repos, so I couldn't quite get that to work. So then I started looking into, okay, what if we isolate some content of the website and start sandboxing how we would build a localization ecosystem and make it on a separate website of its own?

Because I think you remember in that long forum we had several case studies of different tech frameworks that have gone about localization in different ways.

00:24:40 - Anthony Campolo

Yeah, I'm the one who did all those case studies. So yes, I remember.

00:24:45 - Claire Froelich

Yeah. You supplied a lot of those. One of them was React. There was the Storybook case study where they have a subdomain for just their tutorial content, and we're like, oh, maybe we could do something like that. That's what we ended up doing.

We decided to isolate the tutorial because at the time there was one tutorial and it was just a standalone document that could be a good test for localization.

So then it came to the question of, okay, how are we going to build the site? At first I was like, okay, I'll try to learn Cameron JS and see if we can make this work because I'm a big fan of the philosophy that Rob has. It's like, this is just a static website. There's nothing that complicated about it. We just need a little HTML and call it a day. I tried that out, but again I had to hand code the build process. I wanted to do file-based routing, which is fine when you're doing one language, but when you're thinking of how to make it scalable to multiple languages, it becomes a bit more thought intensive.

[00:26:01] I was like, well, maybe I don't need to reinvent the wheel, not only creating a docs framework, but also making it a localizable docs framework.

00:26:11 - Anthony Campolo

At this point in the story, I was watching you go through this process, and I had heard of VuePress way back and knew it was a thing, but I actually dove into it because I realized that it fit this really interesting niche. It was made by Evan You, who is the creator of Vue, and he made it for himself as a tool to write the Vue docs. One of the requirements of the Vue docs is that they had to be in Chinese as well as English. So it was designed to be a multilingual docs site.

I was looking at that and I was like, wow, this looks like it essentially solves our problem. We ended up going with another doc-generating site, but once I dove into it, I realized that there are some people who put a lot of thought and work into this, and there's a lot of prior art to draw on.

00:27:01 - Claire Froelich

Definitely, yeah. And actually, through this whole process, I've learned the importance of not reinventing the wheel. It was very educational. But at the end of the day, like you said, these people have poured a lot of time and thought into making a system that works. And yes, we did end up using a framework. We'll get into that in a second.

But like you say, why reinvent the wheel? One of the things I tried was Docusaurus 1, and I was playing around with it. They had an explicit warning on their docs that said, warning, we recommend that you use Docusaurus 2, which is the new hot thing in town. I go over to the Docusaurus 2 documentation and it looks like they don't have internationalization support yet. So I abandoned that and I was like, okay, back to building my own static site generator.

[00:27:55] It didn't work out. I tried another one called Eleventy. I don't know if you've heard of that static site generator, but I tried that too, which is cool.

00:28:03 - Anthony Campolo

Yeah, we've actually talked about it on the Jamstack book episode. That's one of the featured tools in there. Ben Myers is a really big fan of Eleventy because it has more accessibility focus.

00:28:17 - Claire Froelich

Yeah, it's super simple. I'm very grateful for this journey because I picked up on all these really cool frameworks and things I'd like to use for other projects.

00:28:25 - Anthony Campolo

Yeah, I mean, I love generators. I think they're super cool.

00:28:28 - Claire Froelich

Yeah. And like you were mentioning VuePress and things, I still felt like this is such a simple use case. I don't think we need Vue. We don't need React. We just need to get markdown documents onto the internet. I came to eat my words later.

So at the end of the day, I was getting exhausted from all these attempts that just weren't quite meeting our needs. Finally I happened across a PR on the Docusaurus 2 repo. Somebody was leading an effort to add internationalization to Docusaurus 2, and I was like, okay, let's jump on this. This looks like it's almost ready.

00:29:04 - Anthony Campolo

Could you kind of drill into what that actually means, adding that for this framework specifically?

00:29:09 - Claire Froelich

Adding internationalization.

00:29:11 - Anthony Campolo

Yeah.

00:29:12 - Claire Froelich

Right. So internationalization is the plumbing. It would give Docusaurus 2 the ability to serve this type of content in multiple languages, with the dropdown menus, the sidebars, the SEO, everything. All of that infrastructure-related stuff would be taken care of. On top of that, they were also suggesting a tool for the localization, which is that content translation, and that tool was called Crowdin.

It was the first time I had heard of Crowdin. Up until that point, I was thinking of using a localization manager called GitLocalize because it was free. It was GitHub-based. You just hook it up to your GitHub and it would listen to changes in your repo and tell you, oh, your French is only 70% translated for this document. I thought, perfect. This is how we can get translators in the community aware of our gaps immediately so they can just jump in on the project.

[00:30:17] It turns out GitLocalize is a great budding technology, but it has a lot of bugs. I found that in my trials. So I jumped over to Crowdin and I saw that it's a similar tool. It's free for open source projects because they get all of the translation strings that help with their machine learning. The UI is a bit more complicated than GitLocalize, so at first I was skeptical. Is this going to be easy for translators in the community to jump on board?

But in my research, it was the best thing out there so far. That's actually what we're using now: Crowdin. Anybody with a GitHub account can log in and use it, so it's easy to get started with for developers. This was the recommended technology to pair with Docusaurus 2, and I was like, okay, well I think we finally found a potential candidate for success here.

The only problem was this feature was not released yet. So it was a lot of talking to Sebastien Lorber, who led the Docusaurus internationalization effort, and reading through the source code.

[00:31:20] At the same time, because Docusaurus is a Facebook product. I guess Jest is also a Facebook product, and they were converting their own docs into Docusaurus 2. So I was peeking behind the curtain there and seeing exactly how they were using all of these features that are not documented.

Basically we built the entire Redwood tutorial without documentation from Docusaurus because it was still under development, based on these source code findings and talking to developers in that community. That was a huge learning experience for me, like just seeing what goes into adding such a major feature to a major project. It was fun being a fly on the wall to that, but also just learning how to get into the guts, get into the source code, and see exactly how internationalization works in a framework like this.

00:32:10 - Anthony Campolo

How did you first get connected with Sebastian?

00:32:13 - Claire Froelich

I found him in a PR, I think. Yeah. I was like, have you heard of GitLocalize? Being the naive person I was, I hadn't heard of Crowdin yet. He's like, oh, I'll look into it. But I think he'd already found a good localization manager. So it was just little comments in the PRs and things like that that connected us, I guess.

00:32:33 - Anthony Campolo

It's very cool. Yeah. I'd like to get Sebastian on the show for sure, talk about his side of this journey.

00:32:38 - Claire Froelich

Oh man. He's a wealth of knowledge. Yeah.

00:32:42 - Anthony Campolo

I can only imagine. Why don't you go a little more into detail of what you saw the Jest team going through? What were their biggest concerns, and what were they focused on in terms of what they needed out of Docusaurus?

00:32:57 - Claire Froelich

Well, I don't really look at their conversations so much as their code, so I don't know what they were thinking. But it seems like they had a very clear goal because they already had an existing website that they were migrating from Docusaurus 1 to Docusaurus 2.

00:33:12 - Anthony Campolo

Okay, cool.

00:33:13 - Claire Froelich

So I think they knew what they were getting themselves into, which is something I can't exactly say for myself with Redwood. So that's their migration. It was a migration. It wasn't as much a construction.

00:33:25 - Anthony Campolo

Gotcha. There's probably very low communication overhead as well, both being inside the same organization.

00:33:32 - Claire Froelich

Maybe. I don't know how it's set up over there.

00:33:35 - Anthony Campolo

Yeah, that's a good question. You'd have to ask Sebastian. Always interesting. I always do a lot of tech podcasts, so I hear a lot of people tell stories of cultures at different companies. I find that no matter what, because these companies are so large, there are just so many people and so many teams that it's really hard to have any sort of homogeneous experience across an organization. But you can have aligned philosophies of what the organization is about.

It seems like the processes and the tools end up being very flexible, but everyone who is into it has this big picture of where it's going. So I find that very interesting. It's similar to an open source project where we're all coming from different places, different backgrounds, and different experiences, working on different computers, on different operating systems, deploying to different clouds. It's so much different stuff.

[00:34:32] But we're all trying to do it together and we're all trying to aim at the same goal. It's a really cool thing to see.

00:34:38 - Claire Froelich

Yeah. If you have Sebastian on, I'd love to hear you approach him about this question, because coming to Redwood was my first hands-on experience with open source projects and seeing how that works under the hood. I have this big question for projects like Docusaurus and Jest, because they are open source. You can look online at React, but they also have the name Facebook associated with it. I'm just not really sure what the relationship of those projects is to Facebook and how they organize. So get them on.

00:35:11 - Anthony Campolo

I can recommend you a lot of podcasts where they've talked about what was cool about React. It really was a bottom-up thing in the sense that Jordan Walke just created it, and he had to sell it around Facebook. It wasn't just like, oh, this guy created this thing; we're going to make everyone at Facebook start using it.

So there is a certain culture of you have to actually build something that the engineers of the company want if they're going to adopt it, and the open source projects they're building are being dog-fooded. That's the whole point. It's a multi-pronged thing. They get prestige, they get developers interested in their tech, they get better feedback from users, and then they get all mashed back up into the soup that is facebook.com.

So it's not like an open source project like Redwood because you can't really contribute to it. Honestly, this is the thing people complain about with React, that you can propose a contribution and they'll just be like, no.

[00:36:10] And that's because it doesn't align with their vision. Because they have a very specific vision, a very specific idea of what type of application it needs to serve, which is Facebook. There could be a lot of good downstream effects of that, but it's not something that just anyone can step in and say, I want to do this thing.

So there's a really weird tension there because, like you say, it is open source. You can just look at the source code, but it's not the same kind of free-form, collaborative type thing that it is for other projects.

00:36:39 - Claire Froelich

It's kind of like a hybrid. I mean, there's the benefit to that. They get feedback from the actual users, like in repo, so people that are requesting changes or find bugs, they know about it probably faster than they would if it was closed. They don't have as many eyes on it.

00:36:55 - Anthony Campolo

Indeed. Great. So, hold on. I had a thing. Oh yeah. I'd be curious what your thoughts are on automated translation, if it's useful at all. If it's not going to work for the type of content we're trying to do. I know this came up a little bit in the discussion, but not a ton. It was something that we were like, this is way more complicated than we need to think about. But I would be curious to get your take on it and if you think it's something that's worth pursuing.

00:37:27 - Claire Froelich

So by automated translation, you mean machine translation?

00:37:30 - Anthony Campolo

Yeah.

00:37:31 - Claire Froelich

So I think machine translation has a place. Coming from the field of translation, like ten years ago I thought there's no way that machine translation is ever going to catch up to what a human can wrap their head around, like poetry and all of these types of things. And then slowly over my career as a translator, I was watching Google Translate become more and more powerful.

Actually, there's one sad day at work where I was really stuck on the wording of a translation, and I just thought I'd pop it into Google Translate for inspiration on what kind of words might pop out. It popped out with a great translation that was better than something I thought of, and I was like, uh-oh, I need to get out of this field.

So I'll say, like, machine translation in the last ten years has blown my mind. I think it has use cases for sure.

[00:38:29] Like if you go onto YouTube now and they have auto-translated subtitles, they aren't perfect, but it allows me to watch content and understand it to a certain degree from many more places in the world. So I think that's an example of a good quick-and-dirty use case for machine translation, but quick and dirty being the key word there.

Because when we are talking about the RedwoodJS tutorial, I don't know if any of your listeners have followed through that tutorial, but if you do, you'll see it's very much written in the voice of Rob Cameron, who has a particular artful skill of weaving comedy into the tutorial to make it engaging and fun and relatable, but not in a way that dominates the tutorial. You don't get distracted by all these jokes. It just really helps push you along. It's a very personable read. This is the type of text that doesn't work well with machine translation.

[00:39:32] There's lots of idioms you have to account for. You need a human in the process for this type of translation. That's why we ended up, after talking about, oh, maybe we can just pop a Google Translate plugin and they'll get the gist of it.

But with this open source project, the sense of community is so important. I feel like anybody that's dived into the Redwood tutorial, that's kind of been their entry, their welcome mat into the Redwood world. Personally, I feel like that really had to maintain its personality. The only way we could do that is by having human translators translate it. And not only just human translators, but human translators whose mother tongue is the target language, or at least near native.

We've had amazing people coming to volunteer, like, oh, I'm studying Spanish right now and I'd really like to help out. I'm so grateful for their enthusiasm, but I really feel it's important to get people that know the language. This has been my motto as a translator: you have to know the language well to be able to translate into the language. So for now, human translators using Crowdin as our localization manager.

00:40:45 - Anthony Campolo

Yeah. What you said about how you put in something you needed to translate and got back a good answer, that's kind of what I'm getting at here.

What I think is really cool is that it's not about automating the translation and just not having translators. It's about the synthesis of the two and having some sort of tool to jostle your mind to get you thinking in a new kind of way. And I agree with you that Google Translate especially is just totally blowing my mind.

What I found it useful for, you're talking about the YouTube video captioning. I found a similar thing with news articles and other languages. I wanted to read a news article from a German newspaper or Chinese news, something like that. I could plug it into Google Translate and get a sense of what it's about, the actual informational content of the article. So that's what I found very interesting.

But at the same time, it didn't read like it was translated by a person. There would eventually be weird incongruencies that would be like, okay, I kind of get what you meant, but that's not really what you meant to say. That's where the nuance of being a native speaker is so important.

00:41:59 - Claire Froelich

Definitely. I like what you said there about it being a good tool at the present, kind of like a rubber-ducking tool, helping you maybe think of some words you hadn't thought of if you are doing translation.

I will say the tool we're using, Crowdin, also uses machine translation as a translation aid. You'll have a string-by-string translation tool. You click on a string in the source language. It's going to provide you with ten suggested translations based on their machine learning data of what other translators have translated similar strings. So it's useful to help you get started.

I'm watching this process. I'm like, oh, they're quite clever because now, since they're letting people use this tool for free, if they agree to submit their strings, they're building this huge base of data to plug into their machine learning models. Who knows, maybe even in a short amount of time, we're going to be even more astounded at what machine translation can do.

[00:43:02] But it does depend on the language, especially coming from Japanese, where it's a very contextual language. You never use pronouns unless you really want to emphasize it. You could sit on the train and people will be talking about something. Unless you started at the beginning of their conversation, you aren't going to really know what they're talking about. That doesn't work well with machine translation, and you get a lot of funny translations with Japanese to English, for example.

I did a class at Amazon for call takers that were trying to write emails in English, and they weren't native English speakers. I taught them tricks on how to get machine translation to work for them by adding more context in their source strings. But yeah, I'm impressed.

00:43:52 - Anthony Campolo

Very interesting. Have you ever heard of word vectors?

00:43:56 - Claire Froelich

What's that?

00:43:57 - Anthony Campolo

Yeah, it's a machine learning technique, specifically in natural language processing, which is machine learning done on text data. A vector is like an x, y. It's like a number-coordinate kind of thing. What it does is it takes words and places them on these coordinate positions that can relate them to each other.

So you could have a cluster of dog, cat, horse and then another cluster of car, boat, plane. Then you could have, say, king and queen, and you could have son and daughter or man and woman. You could do like king minus man equals queen. These ways of numerically representing concepts and how they relate to each other in a spatial way totally, totally blow my mind because it gets at that deeper level of what's actually the meaning of the words.

But I always wonder how far we can actually get with this kind of stuff, because eventually it's just boiled down to numbers. So like you say, there's so much more to it.

00:45:09 - Claire Froelich

Yeah. And then there's metaphor and other layers of language as well. I'm reading this book right now called The Stuff of Thought by Steven Pinker, which you might be interested in.

00:45:19 - Anthony Campolo

I read a couple of Steven Pinker books. Yeah.

00:45:21 - Claire Froelich

Ah, okay. I figured it'd be up your alley, but yeah, he touches on these types of things. There are different schools of thought in the realm of interpreting how language is a looking glass into human nature.

00:45:34 - Anthony Campolo

Yeah. Steven Pinker actually wrote the book that has had the most influence on writing for me, in a mechanical sense. It's called The Sense of Style. It's basically just like, how do you write in a way that's clear and concise and actually gets across the thing you want to say. It was super tactical, and the advice it gave really stuck with me because he actually studied linguistics. He understood how grammar works and syntax trees and all that kind of stuff. But then because he also studied neuroscience, he had that brain aspect to it as well. So yeah, he's a cool dude. Good stuff to read.

00:46:18 - Claire Froelich

Yeah. Thanks for the recommendation.

00:46:20 - Anthony Campolo

So let's just go ahead and let our listeners know where we're at right now, where we're trying to go, if we have any languages in the works that are being translated, or if we have any needs or areas we're looking for. If anyone wants to contribute, come join us.

00:46:36 - Claire Froelich

Yes. I will say, since releasing Learn RedwoodJS.com, the subdomain, a new tutorial has come out, tutorial part two. That's an additional several thousand words of text. Since we only have part one translated into French right now, if there are any French speakers listening that would like to get involved with an open source project and give feedback on our translation mechanism, hop on over and get started. Our documents are a click away from getting translated.

As to other languages and things, again, right now, since I think discussions need to be had about goals and stuff for the localization, at this moment it's kind of an availability basis. So if you are interested in translating it into Indonesian or Spanish or something, it's very easy to get started. You can head over to Learn RedwoodJS.com and click on the GitHub link and open an issue, and we can get you started real quick on a new language.

That being said, moving forward, I think now that we finally have a mechanism for inviting new translators, I need to start thinking about community building.

[00:47:59] Because we've had four different people involved with translation so far. But you come in and then you go off and do other projects. I'm looking at how other projects like TypeScript and Gatsby are approaching localization of their documents, and they have a community in their Discord channels for each localization language so that people can meet other localizers that are interested in the same content and ask each other questions, maybe come up with a glossary, but more importantly, build that sense of community that makes people want to come back and contribute translations again.

On the same note, I feel there's a great need to better recognize the people that have contributed, because I would consider them contributors to Redwood. Right now it's not quite in place, so I'd like to beef that up, maybe with some sort of incentivizing badge system, or at the very least getting them onto the contributors list.

00:48:57 - Anthony Campolo

I would say that's definitely a no-brainer. That would be the least.

00:49:02 - Claire Froelich

Yeah.

00:49:03 - Anthony Campolo

Well, thanks so much, Claire. I really enjoyed this conversation. Where can our listeners reach you?

00:49:08 - Claire Froelich

You can find me on Twitter now. I have a Twitter. It's @clairefror, C-L-A-I-R-E-F-R-O-R. Or you can find me on GitHub, just @clairefro without the R, C-L-A-I-R-E-F-R-O. Yeah, those are the best ways to reach me.

00:49:28 - Anthony Campolo

Have a good one, everyone.