OmniDocCompilation error after LaTeX translation, how to troubleshoot step by step
Compilation fails after LaTeX source file is translated into Chinese? This article explains how to read the compilation log, how to judge which category the error report belongs to, how to fix various problems, and how to avoid making the same mistake next time, in order from the easier to the harder.
Key points of this article
- If compilation fails, first check the first error and the corresponding line number in the log. Later errors are often a chain reaction. If you fix the first error, the later ones will often disappear.
- Source files containing Chinese usually require xelatex or lualatex with the ctex macro package. Direct compilation with pdflatex is a common cause of failure.
- During translation, formulas, command names, environment names, \label and \cite key names must remain intact, and only natural language paragraphs are translated.
- Only make one change at a time and recompile to determine which change actually solves the problem.
If you translate a LaTeX source code package into Chinese, and the screen is full of red letters when you recompile, or the PDF cannot be generated at all, this article is written for you. When many people encounter this situation, they will directly go through it again, and the error remains the same. In fact, most compilation failures can be found in the specific location in the source file, and can usually be recovered by changing a few lines.
After reading this article, you will know how to read the compilation log, how to determine which category the error report belongs to, and how to fix each type of problem. What I’m talking about here is a general troubleshooting method that doesn’t rely on a specific tool. It only cares about the failure of post-translation compilation and does not discuss the translation method itself.
The following content is unfolded in order from easy to difficult. You can first find out your situation by referring to the table, and then follow the steps to check item by item.
Do you need to re-translate the compilation error? One sentence conclusion
In most cases, there is no need to re-read. You can first look at the log to locate the error location, and then modify the source file according to the reason. The table below gives common situations and corresponding practices.
| your situation | Recommended practices | reason |
|---|---|---|
| Chinese characters are displayed as squares, or the prompt characters cannot be encoded | Use xelatex or lualatex instead, and load the ctex macro package | pdflatex does not directly support Chinese characters by default |
| The error line falls in the formula | Check whether the translation has put Chinese characters into a mathematical environment or changed the symbols by mistake | The rules for text and symbols in math mode are different from those in the main text |
| The prompt command is undefined and the command name becomes Chinese. | Restore the command name to its original text | When translating, the commands were translated as ordinary words. |
| Only citations, figures, or references report an error | Check \label, \ref, \cite key names and file names | After the key name was changed, the cross reference could not find the target. |
| There are many errors and they are scattered everywhere | Compare it section by section with the original file, or comment out half of it to narrow the scope. | It may be a batch replacement or encoding problem, segment by segment positioning is faster |
First determine what kind of problem it is
After getting the error report, first match the symptoms with common causes, which can save a lot of invalid attempts. The following table lists several common types of post-compilation problems.
| symptoms | Common causes | How to confirm |
|---|---|---|
| Prompt Undefined control sequence, the name is Chinese or strange characters | Command names are translated | Search the source file for the name of the error message to see if it follows a backslash |
| Tip Missing } inserted or Extra } | Incorrect number of braces | Count { and } one by one near the error line, and pay attention to the full-angle brackets in the translation. |
| Presentation \begin{...} ended by \end{...} | Environment tags are not paired | Search all \begin and \end, check number and environment name |
| Chinese garbled characters, or prompts that Unicode characters cannot be processed | The compilation engine or file encoding is incorrect | Make sure the file is saved as UTF-8 and use xelatex or lualatex instead |
| Tip Missing $ inserted | Math mode is not closed | Check for unclosed $, \( or \[ in the translation |
| Prompt File not found, or the picture is not displayed | The file name or path has been changed | Check file names in \includegraphics and \bibliography |
| References are shown as question marks | The key name is inconsistent, or the reference is not regenerated | Check the \cite key name with the key name in the bib file, and compile it a few more times |
Check and repair item by item
It is recommended to check in the following order. The earlier steps usually save trouble.
- Read the log first and look for the error at the top. Lines starting with an exclamation point in the log are errors, and the l. followed by a number is the line number of the source file. Only deal with this error, fix it and then recompile to see if subsequent errors are reduced.
- Return to the line where the error was reported and compare it with the original text. Look at the translated line and the corresponding paragraph in the original text side by side. Common differences are extra curly braces, translated command names, or full-width symbols.
- Confirm the compilation engine. Source files containing Chinese usually require xelatex or lualatex, and the ctex macro package is loaded in the preamble area (for example, writing \usepackage{ctex}). After changing the engine, do not change other content first and see if the Chinese can be displayed normally.
- Check the pair structure. Check that \begin and \end, curly braces, and $ symbols are paired one by one. A common problem in translation is mistaking the full-width "{" and "}" for curly braces, or leaving unclosed $ in the paragraph.
- Check the command and key names. Search the source file for all commands starting with a backslash to confirm that they have not been translated into Chinese; then check that the key names of \label, \ref, and \cite are exactly the same as the original text.
- Check the resource path. Make sure the pictures, bib files and the main file are in the same directory, or the path is written correctly, and the case of the file name must be consistent with the original text.
- Recompile every time you make a change. If you change a lot at once, you won't be able to tell which step worked when something goes wrong.
How to fix Chinese display exception
First check whether the Chinese macro package is loaded in the introductory area, then confirm that the file is saved as UTF-8, and finally change the engine to xelatex or lualatex. If only individual characters appear as squares, it is usually because the font is missing. You can change to an installed Chinese font in the font settings of ctex.
How to fix formulas and commands that have been mistranslated
The symbols, variables and commands inside the formula should remain in the original text, and only the explanatory text before and after the formula should be translated into Chinese. If you can't determine where the problem is, you can use the dichotomy method: use % to comment out the first half of the main file and recompile; if it passes, the problem is in the second half, so gradually narrow the scope.
How to fix quotes and pictures that cannot be found?
Cross-references and references require multiple rounds of compilation to generate complete results, so compile two or three more times when question marks appear. If the question mark still exists, go back and check the key name. If the image error is reported, focus on whether the path and extension are consistent with the original file.
How to avoid it happening again next time
- Keep a copy of the original version before translating, and confirm that the original text can be compiled normally. If the original text itself reports an error, it will be impossible to determine whether subsequent problems are caused by the translation.
- Make an unchangeable list before translation, including all commands, environment names, formulas, \label, \cite key names and file paths. Only natural language paragraphs are allowed to be modified.
- Unifiedly save the source files as UTF-8, and fix the Chinese settings in the introductory area to avoid having to readjust every time you change the environment.
- Compile first after translation, and then manually check it paragraph by paragraph after confirming it is correct. The results of machine translation will inevitably have omissions or mistranslations, and important content such as papers and contracts especially need to be checked sentence by sentence.
- Save a version every time you complete a chapter. When an error occurs, you can roll back to the last compilable state without having to troubleshoot from the beginning.
❓ Frequently Asked Questions (FAQ)
1. There are many warnings in the log. Do you want to deal with them all?
No need. Warnings usually do not prevent PDF generation. First deal with errors starting with an exclamation point. After clearing the errors, see if there are any warnings that affect reading.
2. When using pdflatex to report an error, it can be compiled by replacing it with xelatex. Does this mean there is no problem with the translation?
uncertain. Changing the engine only means that the Chinese encoding and font problems have been solved. There may still be errors in the curly brackets, command names and key names in the translation. You need to continue to check according to the above steps.
3. If you want to retain the original format, how should you set it during translation?
You can upload the LaTeX source code package at omnidoc.top, select translation only or bilingual comparison and then download the results. No matter which method you choose, it is recommended to use the above checklist to check formulas, cross-references and file paths, and then recompile and confirm.
4. When choosing latex Chinese translation software, what indicators should you look at?
Prioritize whether it retains formulas, commands and cross-references, supports the entire source code package, and has instructions for file size and privacy. If you can only get segments of plain text, you will still get a lot of structural errors during compilation.
📝 Summary
Compilation errors are reported after LaTeX is translated into Chinese. In most cases, it is a problem with the engine, curly braces, command names or key names. It can be solved by modifying the errors at the top of the log one by one. Insisting on making only one change at a time and compiling and then checking after translation can significantly reduce repeated rework.
