Jak postępować z blokami kodu i Front Matter podczas tłumaczenia dokumentacji technicznej w Markdown?
“Bloki kodu, kod w tekście (inline) oraz sekcje konfiguracyjne (Front Matter) w dokumentacji technicznej, jeśli zostaną przetłumaczone, mogą spowodować, że dokument stanie się nieużyteczny.”
Analiza przyczyn podstawowych
Sprawdzanie zawartości kodu i znaczników
Obecny proces wyodrębnia treści do tłumaczenia zgodnie ze strukturą Markdown. Kod w tekście może być wyodrębniany razem z otaczającym go tekstem, a komentarze w blokach kodu również mogą trafić do tłumaczenia. Po tłumaczeniu sprawdź znaczniki takie jak ``` i ` oraz składnię i logikę przykładów Python i JS. Nie zakładaj, że wszystkie obszary kodu będą pomijane.
Ochrona metadanych Front Matter
W przypadku konfiguracji YAML na początku dokumentu (Front Matter), typowej dla statycznych blogów takich jak Jekyll/Hugo, obecny proces wyodrębniania nie traktuje wartości pól takich jak `title` i `description` jako osobnych tekstów do tłumaczenia. Po tłumaczeniu sprawdź metadane ręcznie i zachowaj parametry budowania, takie jak `date:` i `slug:`.
Sprawdzanie źródła tabel Markdown
Po tłumaczeniu tabel Markdown zmiany długości tekstu mogą powodować różnice w wyrównaniu kolumn w źródle. Sprawdź znak `|`, wiersz separatorów i zawartość komórek, a w razie potrzeby ręcznie uporządkuj źródło tabeli.
Podsumowanie rozwiązania końcowego
Stworzony specjalnie dla społeczności open source i deweloperów, zapewnia zachowanie profesjonalizmu oraz czytelności plików README.md i instrukcji technicznych podczas zmiany wersji językowej.