French Translation: Layout & Tooling For Catala Book

Hey guys! We're diving into a crucial discussion about translating the Catala book into French. This is a big step in making Catala accessible to a wider audience, so let's explore the best approaches for layout and tooling. Our goal is to figure out which method will give us the highest quality translation while also being maintainable and contributor-friendly.

mdbook-i18n-helpers with gettext: A Validated Approach

One option we're looking at is using mdbook-i18n-helpers with gettext. This seems to be the standard approach for mdbook, and it's used by some pretty large projects like Rust by Example. Basically, this method uses gettext for internationalization, which means we'd end up with a localized .po file that contains all the translations. You can see an example of what this looks like in this file.

mdbook-i18n-helpers offers a structured way to manage translations, which can be a huge benefit when dealing with a complex project like the Catala book. This approach allows for clear separation of the original text and its translations, making it easier to track and update content. Furthermore, the tooling around gettext is quite mature, providing features like translation memory and terminology management that can improve consistency and quality. However, it's not all sunshine and roses. Some projects, like Cairo Book, have actually removed this infrastructure, and others are facing maintenance issues. For example, the Spanish translation of Rust by Example is currently unavailable. So, while it's a validated approach, it might be a bit unwieldy, and we need to consider the potential maintenance overhead.

The main advantage of using mdbook-i18n-helpers is its established track record and the support it offers for managing translations in a structured manner. This can be particularly beneficial for large projects, where consistency and accuracy are paramount. However, the drawbacks include the complexity of the tooling and the potential for maintenance issues. It is imperative to carefully weigh these factors against the project's specific needs and resources before making a decision.

Parallel Books with a Custom UI Toggle: A Prose-Like Alternative

Another idea is to create two parallel books – one in English and one in French – and then use a custom UI toggle to switch between them. This approach would allow us to have more prose-like translations, which could make the French version read more naturally. Imagine having two separate versions of the book, each crafted to feel native in its respective language. This could lead to a more enjoyable reading experience for French speakers. However, this method also has its downsides. The biggest concern is that the two versions could easily drift out of sync. Keeping them aligned would require a lot of manual effort and coordination. It's also worth noting that this approach might be easier for first-time contributors, as they wouldn't need to deal with the complexities of gettext.

The parallel books approach offers the advantage of greater flexibility in translation, allowing for more natural and idiomatic French. This can enhance the readability and overall user experience. Additionally, it might be easier for new contributors to get involved, as they can focus on writing prose rather than grappling with complex translation tools. However, the significant drawback is the potential for divergence between the two versions, which could lead to inconsistencies and inaccuracies over time. A robust system for tracking changes and ensuring synchronization would be essential to mitigate this risk.

This method shines in its simplicity and potential for creating a more natural reading experience. Contributors can focus on crafting high-quality prose without needing to learn complex tooling. However, the risk of content drift between the two versions is a significant concern. Regular audits and updates would be essential to maintain consistency and accuracy.

Key Considerations and Trade-offs

Both approaches have their merits. The mdbook-i18n-helpers/gettext method has validated tooling support, which can be a huge time-saver. On the other hand, the parallel books approach might be more legible and easier for first-time contributors. So, how do we decide? Here are some key factors to consider:

• Maintainability: How easy will it be to keep the translations up-to-date over time? The gettext approach may require more technical expertise, while the parallel books approach may require more manual effort.
• Consistency: How important is it that the English and French versions are perfectly aligned? The gettext approach will likely provide better consistency, while the parallel books approach may allow for more flexibility.
• Contributor Experience: How easy will it be for new contributors to get involved? The parallel books approach may be more welcoming to non-technical contributors.
• Resource Availability: What resources (time, money, people) do we have available for this project? The gettext approach may require more upfront investment in tooling and training, while the parallel books approach may require more ongoing effort for maintenance.

Diving Deeper: Pros and Cons

Let's break down the pros and cons of each approach in a more structured way:

mdbook-i18n-helpers with gettext

Pros:

• Validated approach with established tooling.
• Good support for managing translations.
• Potentially better consistency between versions.

Cons:

• Can be unwieldy and complex.
• May require more technical expertise.
• Potential for maintenance issues (as seen in other projects).

Parallel Books with Custom UI Toggle

Pros:

• More legible and prose-like translations.
• Easier for first-time contributors.
• Greater flexibility in translation.

Cons:

• High risk of drifting out of sync.
• Requires more manual effort for maintenance.
• May require more ongoing coordination.

Making the Decision: A Call for Input

Ultimately, the best approach will depend on our specific goals and constraints. We need to weigh the pros and cons of each option carefully and consider what's most important to us. Are we prioritizing consistency and maintainability above all else? Or are we more concerned with creating a natural and engaging reading experience for French speakers?

I'm really interested to hear your thoughts on this, guys. Which approach do you think would be the best fit for the Catala book? Do you have any experience with either of these methods? Are there any other options we should be considering? Let's discuss!

By carefully considering these factors and gathering input from the community, we can make an informed decision that will set us up for success in translating the Catala book into French. This is a critical step in making Catala accessible to a wider audience, and I'm excited to see what we can accomplish together. Let's make this translation the best it can be! Your insights and experiences are invaluable as we navigate these choices together.