Modifying Translation Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
Modifying translation guidelines in "The Architecture of Open Source Applications" (AOSA) project is a collaborative effort aimed at making technical architectural knowledge accessible to a global audience. The project operates under a Creative Commons Attribution 3.0 Unported license, which explicitly allows for the reuse and translation of content provided that original sources and authors are cited. Guidelines for modification emphasize open contribution, technical accuracy in representing complex software structures, and community coordination.
Sources: CLAUDE.md, metadata/faq.html.md:46-56, metadata/index.html.md:183-190
Translation Infrastructure and Workflow
The translation process involves transitioning from original English Markdown files to localized versions while maintaining structural integrity. For the Korean translation, this includes managing local image assets to replace remote URLs, ensuring that architectural diagrams remain contextually relevant.
Asset Management
A critical part of modifying translation content is the local organization of images. The project uses systematic mapping to ensure that translated Markdown files reference local paths rather than remote URLs from the original aosabook.org site.
The diagram shows the workflow for converting remote image references to local assets during translation.
Sources: download_summary.md:3-10, download_summary.md:76-80
Document Structure
Translations must follow the established directory and naming conventions of the source repository to maintain consistency across volumes.
| Component | Guideline |
|---|---|
| Directory | Maintain hierarchy (e.g., volume1/, volume2/, posa/, 500lines/) |
| File Naming | {chapter-number}_{chapter-name}.html.md |
| Metadata | Translate index, FAQ, and licensing information in the metadata/ directory |
| Images | Store in korean_translation/[volume]/images/ |
Sources: CLAUDE.md:20-40, download_summary.md:14-18
Localization Guidelines for Technical Content
Translating AOSA requires more than literal word replacement; it requires accurate representation of software architecture and developer intent.
Handling Technical Terminology
When modifying content for localization, maintainers must decide between translating terms or keeping them in English. In the Battle for Wesnoth chapter, specific technical identifiers like "WML" (Wesnoth Markup Language) or "DAG" (Directed Acyclic Graph) are core architectural concepts that often remain in English or are provided with clear localized explanations.
Internationalization Support (i18n)
The project documentation highlights that some systems being described, such as Battle for Wesnoth, have their own built-in translation mechanisms. For example, WML uses an underscore prefix for translatable attribute values, which are converted using GNU gettext.
# Example of translatable WML used in source documentation
[unit_type]
id=Elvish Fighter
name= _ "Elvish Fighter" # The underscore indicates a translatable string
advances_to=Elvish Captain,Elvish Hero
[/unit_type]
Sources: volume1/25_wesnoth.html.md:118-132, korean_translation/volume1/12_mercurial.html.md:46-50
Contribution and Legal Requirements
Modifying or starting a new translation requires adherence to specific legal and community standards.
Licensing and Royalties
All modified content and translations must be released under the Creative Commons Attribution (CC-A) license. While not strictly enforced, the project strongly encourages that royalties from the sale of translated editions be donated to Amnesty International, consistent with the original project's mission.
Communication Flow
Prospective translators and those wishing to modify existing guidelines are instructed to contact the project coordinators.
The sequence diagram illustrates the communication and licensing agreement required for translation contributions.
Sources: metadata/faq.html.md:46-56, metadata/faq.html.md:88-92, metadata/index.html.md:183-190
Conclusion
Modifying translation guidelines in the AOSA repository is governed by the principles of open access and technical precision. By maintaining strict directory structures, utilizing local asset mapping, and adhering to CC-A licensing, the project ensures that high-level architectural insights are accurately preserved across different languages.
Sources: CLAUDE.md, metadata/faq.html.md, download_summary.md