Stata programs frequently travel between universities, research teams, government agencies and analysts who work in different languages. The statistical method must remain stable, but the command’s usage instructions, options, help file, labels and error messages need to be understandable to the person running it. This guide explains Stata ado-file localization, the syntax command, option parsing, SMCL help files, Unicode output and multilingual research-log quality assurance without letting translation change the statistical results.
If you want to localize a Stata command, write a readable .sthlp file, understand syntax varlist and options, translate a Stata display as error message or test Unicode in statistical logs, the first distinction is between commands Stata executes and words that humans read. A syntax declaration is executable grammar, not ordinary prose. The help page and human diagnostics explain that grammar, but changing an explanation must not silently change what the program accepts.
The examples begin with a harmless custom command that prints a fictional label rather than reading or changing observations. From there, we examine variable names, macro expansion, options, sample selection, help rendering and reproducible publication. This is for international users who need clear, conversational guidance, with enough technical precision to trust a research workflow. It does not assume that every Stata release or installed user command has the same interface.
Quick answer
- Keep Stata commands, option names and program syntax exactly as the installed code expects.
- Translate purpose, examples, human messages, help navigation and results explanations.
- Use
syntaxdeliberately to parse the documented argument contract. - Review SMCL markup and Unicode in the Stata Viewer and logs separately.
- Test that statistical outputs and returned values remain unchanged across language versions.
Start with a read-only ado-style helper
* A harmless demonstration for a scratch Stata session.
program define preview_label
version 17.0
syntax , LABEL(string)
display as text "Preview label: `label'"
end
* Test with a fictional label:
preview_label, label("Résumé sample")This custom command accepts a string option and displays a label. It does not load data, alter observations, estimate a model or write a report. For a persistent ado-file, the file name, program name and command naming convention should agree. Run the example in a disposable session; if the name already exists, choose a different scratch name rather than overwriting a program you rely upon. The declared version is a compatibility anchor, not a claim about every later release.
Why custom commands need a clear contract
A Stata command is an interface between the analyst’s request and the program’s instructions. That interface includes the command name, positional arguments, option names, allowed variable lists and possible errors. Translating only the introductory paragraph is not enough if the user cannot determine which words to type. Conversely, changing executable option names to local-language words without modifying and testing the parser can make the command fail. Document the exact original syntax and give readers a local-language explanation of each element. This keeps language support from becoming an accidental change in behavior.
What the syntax command does
The built-in syntax command is commonly used inside ado-programs to parse user-supplied arguments and options. It establishes which forms are accepted and organizes values for the program to use. A translated manual should reflect the syntax declaration actually implemented, including required and optional parts. If a script accepts one required string option, the help must not imply that the string can be omitted. If the parser allows a varlist or qualifiers, explain those separately. Translation does not repair an undocumented discrepancy between the declared grammar and the real behavior.
Keep option names stable unless aliases are real
Stata options are executable tokens. A help page in Spanish can describe a required label option in Spanish while displaying the actual command keyword label() if that is what the program recognizes. A localized spelling becomes a supported interface only if the developer has explicitly implemented and tested it. This distinction helps collaborators share scripts across countries. They can change explanatory text without changing the code required for reproducible analysis. Avoid giving an untested local-language command example that looks plausible but cannot run.
Understand the difference between strings and variables
A string such as ‘Quarterly sample’ is text, whereas a Stata variable name identifies a column in the dataset. An example that asks for a label should not be confused with one that asks for a variable list. Translators need context: ‘variable’, ‘value’, ‘label’, ‘macro’ and ‘option’ have different technical meanings. The documentation should show which form a user enters and what it controls. When in doubt, use a safe example from a synthetic dataset, not an identifiable research record. A fluent but technically imprecise translation can lead analysts to the wrong command.
Local macro names and displayed wording
Stata programs often use local macros to hold parsed option values and intermediate results. The backtick and apostrophe characters around a local macro reference are part of executable syntax, not decorative quotation marks. Editors who replace them with typographic marks can break a program. Keep code samples in protected blocks and review copied text in the Do-file Editor. The surrounding description can use normal punctuation and the target language’s conventions. Learning the difference between code delimiters and prose quotation marks makes multilingual technical writing much more reliable.
Use display with an explicit purpose
The display command can show a human-readable message or a value, and its as text or as error styling affects presentation. A message displayed in a research log may be read by a person, imported into another document or mistaken for a result. Explain what the message means rather than simply translating individual words. A preview label is not a statistical estimate. A validation message is not a data row. Clear distinctions help multilingual readers understand what to trust and what to correct after a failed invocation.
SMCL is formatting, not ordinary text
Stata uses its markup and control language, SMCL, for help and other formatted output. Braces can have special meanings in this context, and a string containing an SMCL directive is not necessarily displayed literally. That matters when localizing text with curly braces or assembling messages that include user-supplied data. Translate the visible words while protecting valid directives and required markup syntax. Test the displayed result inside Stata, because text that looks fine in a code editor may behave differently after the Viewer interprets it.
Why .sthlp files matter
A user-written command can have a companion .sthlp help file that explains purpose, syntax, options, saved results, examples and limitations. The file is a real part of the interface rather than a decorative attachment. Reviewers should navigate it in Stata’s Viewer and ensure that links, anchors and formatting still work after translation. If the help promises a default or a return value that the ado program does not provide, that documentation error can damage reproducibility. Start from the actual command contract and build reader-facing guidance around it.
Research logs need a stable interpretation
Research teams often preserve log files to show what commands were run and what Stata reported. A translation may make explanatory messages easier to read, but it should not alter the numerical estimates, test statistics or identifiers that another analyst uses to verify the calculation. Keep a documented separation between stable results and localized narrative. Compare reference runs on controlled data under supported language choices. If a later version changes an output table or statistic, investigate the software and model first rather than assuming the language caused it.
Parsing and documenting a real command for international users
Preserve varlist meaning
A varlist identifies one or more dataset variables; it is not a sentence to be translated. A documentation writer should explain whether a command accepts numeric variables, factor-variable notation or a specific count, and whether variable abbreviations are permitted. These details influence which observations and measurements the program analyzes. A translation must not change the variable order in an executable example or imply that a free-form human label is a variable name. Use a tiny fictional dataset to demonstrate correct syntax. Verify that the same varlist is accepted across language versions and that numerical results remain identical.
Explain if and in qualifiers
Many Stata commands support if and in qualifiers to restrict observations. These are recognized elements of Stata syntax, not ordinary English conjunctions to replace inside runnable code. Their conceptual explanation should say how they select observations and what assumptions apply. A localized example that accidentally drops a qualifier can estimate a model on a different sample. In a serious workflow, compare the sample size and any marked observations before approving translated instructions. The distinction matters because an apparently small wording change can change the population being analyzed.
Separate options from the comma
Stata’s command grammar often places options after a comma. A user unfamiliar with the convention may read it as optional punctuation and omit it, causing an error. Explain the command structure visually: command name, required arguments, any qualifiers, comma, and options. Preserve copyable punctuation and show one working example, followed by a deliberately invalid one with its correction. Such instruction is more valuable than merely saying ‘add your options’. The same parser contract applies regardless of the natural language of the help page.
Document required and optional values
A flag without an associated value is different from an option that requires a string, numeric value or variable name. The syntax declaration describes which is expected. A translated help table should state whether each option is mandatory, its accepted type, the default if omitted and the meaning of invalid input. If a value is required, give an example that includes it. Avoid descriptions such as ‘include as desired’ when the program will reject an empty field. Practical clarity reduces the number of support requests from people learning the command in another language.
Understand parsed local macros
The syntax command can make parsed values available through local macros. The program’s later instructions refer to those values through Stata’s macro notation. A code example should maintain the exact punctuation that the Stata interpreter expects. Do not let a typography engine replace a backtick, apostrophe or quote with a visually attractive character that changes the program. In prose, explain how a required option becomes a local string or how a parsed varlist is used in later operations. This shows the full path from typed command to behavior.
Treat default settings as methodological choices
A statistical command may choose an estimation method, confidence level or handling rule when an option is omitted. Defaults can affect results, not merely convenience. If a translation hides or misstates them, different readers may make incompatible assumptions even while running the same code. Document the implemented default beside the option and confirm it on a synthetic test. If different Stata versions have different behavior, anchor the guidance to tested releases. Reproducibility depends on transparent assumptions, and multilingual documentation is one place where those assumptions should be easy to find.
Do not translate statistical return names
Stata results may be stored in r(), e() or other structured locations depending on command type and design. Such names and result identifiers are part of the programmable interface. An article can translate ‘standard error’ or ‘sample size’ for a human reader, but it should not invent a localized version of a returned scalar that users cannot retrieve. Provide the literal identifier with an explanation of its meaning, unit and conditions. Test that the returned data remain available and numerically consistent across localized messages.
Distinguish command errors from methodological warnings
An invalid option is not the same as an estimator warning about insufficient data, singularity or another scientific condition. Human messages should preserve severity and the correct next step. Translate the reasoning carefully: ‘no observations’ does not necessarily mean ‘the command is broken’. A reproducibility review should check that warning categories and return codes do not become misleading after localization. If a message affects whether a result can be reported, involve a domain expert in addition to a fluent language reviewer.
Use display as error appropriately
Stata’s display as error is designed for messages that should appear in an error style and can behave differently from merely inserting SMCL formatting codes. It should not be replaced with an arbitrary display string because the styling may affect output suppression and interpretation. Review the application’s real error state and message content together. A translated error should name what failed and help the user recover, while preserving the underlying program control flow and appropriate return behavior. Never style an ordinary success notification as though it were a critical failure.
Avoid leaking identifiers through diagnostics
A command may process confidential variables or datasets. An error that repeats the whole supplied command or private paths can reveal information in saved logs or screenshots. Use a minimal diagnostic that identifies the invalid option, required form or affected parameter class without printing unnecessary sensitive values. Public documentation should demonstrate failures with fictional variable names. Translate warnings naturally but do not make privacy trade-offs merely for the sake of a verbose message. Teams should review logs as potential disclosure surfaces during localization testing.
Understand what quietly suppresses
Stata supports quietly and related output control in workflows that may run many commands. A localized message can appear or disappear depending on whether it is emitted as ordinary output, an error or another kind of result. Documentation should explain when a user should expect to see text and which messages remain essential in unattended scripts. Do not assume that adding an SMCL style code alone reproduces the semantics of display as error. Tests should cover interactive execution and batch or quiet invocation as distinct contexts.
Check help navigation as an interface
In Stata, help is often read inside a Viewer with links to related commands, sections and examples. A multilingual help file must preserve navigational structure, valid tags and links that resolve to actual installed content. Translate visible headings and explanatory text, but protect the syntax of SMCL directives. Clicking every important link is a meaningful test, because a page that looks readable may still lead to a nonexistent help topic. If the translated page refers to a separate command, make the relationship explicit rather than implying it is part of the same program.
Keep examples compatible with installed versions
An ado-file may declare a version or rely on features introduced in specific Stata releases. A public guide should identify what was actually tested rather than present one code sample as universal. The syntax command, Unicode handling or formatted help behavior can vary across historic versions. Where compatibility matters, keep a stable minimum and document newer alternatives separately. A reader who sees a version error should not be encouraged to change random translations. Instead, check their installed release, program dependencies and referenced syntax.
Make Unicode tests meaningful
Stata offers Unicode-aware functionality, but international readiness involves more than storing UTF-8 text. Test accents, Chinese, Japanese, Arabic and other required scripts in program messages, help files, exported tables and logs. Distinguish whether a string was preserved in memory from whether a font renders it correctly. Some environments may export text using an additional file encoding, so the final artifact deserves inspection. Use disposable labels instead of real client names or confidential research participants. Test the exact Stata platform and version used in production.
Beware of typography that changes code
Backticks, apostrophes, double quotes, braces and brackets can have special meanings in Stata syntax or SMCL. Translation editors often prefer typographic quotation marks, but such changes can make a copied command invalid. Separate human narrative from code snippets and test copying from the published page into the Do-file Editor. The sample should run without editorial repairs. This task is especially important for right-to-left languages, where visual order may differ from the stored character order and punctuation can appear next to Latin code tokens.
Translate output tables with methodological context
A table header such as ‘SE’ may refer to a standard error, while ‘N’ may represent observations. A literal but ambiguous replacement can mislead a reader about the calculation. Create a glossary of statistical terms with their definitions, units and accepted target-language renderings. Use the glossary consistently across screen output, log annotations and reports. However, keep identifiers required by downstream scripts stable unless the machine interface intentionally supports a documented alternate schema. A review must compare the actual estimates, not just the labels around them.
Separate raw logs from reader reports
A Stata log can act as an audit record, while a polished report may use translated captions and explanations. These artifacts have different purposes. If a downstream system parses the log, spontaneous changes to labels can be disruptive. Consider preserving the raw analytical record and producing a separate reader-facing report with localized descriptions. Document which is authoritative for reproducibility. Translating a report should not replace the original command history or remove warnings that were important to interpreting an estimate.
Prepare a bilingual error glossary
A good glossary goes beyond equivalent words. It maps common error conditions to their cause, expected user action and the exact Stata construct involved. For example, a missing option differs from an unknown variable, an invalid number and an empty sample. A reviewer can then check whether the translation gives the right instruction. Stable categories also help support teams who work across languages. They can ask for an error identifier or minimal redacted reproduction instead of trying to reverse-engineer vague localized prose.
Test on a synthetic dataset first
A localization release should be safe to reproduce. Build a small fictional dataset containing a numeric outcome, a grouping variable and a few controlled missing values. Record the reference calculation and sample size. Run the same program with each supported locale or translated message set, confirming the underlying statistics do not change. This catches mistakes where help examples drop an if qualifier or change the option that selects a model. Never use live patient, employee or student records merely to check translated messages.
Describe the exact handover package
A user-written Stata command needs more than an ado-file if colleagues are to rely on it. Include its help file, supported versions, dependencies, example commands, saved-result documentation, known limits, glossary and reproducibility tests. The translation team should understand which words they may edit and which tokens are executable. The technical team should understand which locale variants have actually been reviewed. This small division of responsibility prevents last-minute linguistic edits from invalidating code and lets future users troubleshoot without contacting the original author.
Worked scenarios for international Stata users
A public-health researcher works in two languages
A team uses the same Stata program to summarize a fictional health dataset in English and French. The descriptive headings are translated, but the variables, sample restrictions and commands are unchanged. Reviewers compare observation counts and statistics before discussing wording. An early draft confuses ‘prevalence’ with ‘incidence’, and a subject specialist corrects the concept. The project learns that a fluent sentence can still assert the wrong analytical fact. Its release requires both a linguistic sign-off and a numerical equivalence check on controlled data.
An option is translated into a nonexistent command
A Spanish-language guide describes a string option by replacing its actual keyword with a plausible Spanish word inside a runnable command. Users receive an unrecognized-option error. The editor restores the canonical Stata option and explains its meaning in Spanish in surrounding prose. If the team ever wants localized option aliases, those must be implemented in the parser with compatibility tests. Simply editing documentation cannot change executable grammar, and keeping that boundary explicit helps analysts share identical scripts across countries.
A required comma disappears in an example
A newcomer copies a command from a multilingual instruction page, but the comma separating arguments from options has been removed during editing. The resulting syntax error appears mysterious because the translated description says the value was supplied correctly. A copy-paste test from the final rendered page identifies the punctuation omission. The guide is corrected with distinct code formatting and a brief explanation of Stata’s common comma-before-options convention. The user can now see which characters belong to the command and which belong to its description.
A variable label is mistaken for a variable name
A translator sees the displayed phrase ‘Weekly income’ and uses it as though it were the underlying Stata variable identifier. The program expects a varname, not an ordinary multiword caption. A reviewer explains the difference among variable names, variable labels and option string values, using a small synthetic dataset. The help page then shows a genuine variable identifier in the executable command and the translated label in explanatory output. This keeps machine references stable while allowing readers to understand what each measure means.
A local macro reference is smart-quoted
A content system turns a code backtick into typographic punctuation. The Stata macro no longer expands as intended, and the example prints the wrong information or fails. Rather than troubleshooting encoding at random, the technical reviewer compares the copied text with the original literal code. The publication workflow preserves the exact macro delimiter characters and places explanatory language outside protected snippets. This small distinction matters because a backtick and an opening curly quotation mark are not equivalent characters to the Stata interpreter.
An if qualifier is omitted in translation
A translated example of a regression loses its if restriction, so the command processes a different sample than the reference. The resulting coefficients are not directly comparable. A domain reviewer finds the missing qualifier during a synthetic-data test, and the guide is corrected. The lesson is that executable examples can carry methodological assumptions; editing them as if they were ordinary sentences creates risks. The final review compares the sample size, conditions and returned results, not merely whether the command runs without an error.
A confidence level is misunderstood
A statistics help page describes an option that controls confidence level. Its translation suggests the value is a probability threshold in an unrelated sense. A reviewer adds context about the resulting interval and verifies the actual accepted values and default. The surrounding message becomes easier to understand while the option name and numeric contract remain unchanged. This is more useful than literal translation because the user can connect the input to the reported statistic without making unsupported claims about certainty.
A help file renders blank text near braces
A localized .sthlp file contains braces that Stata’s SMCL renderer interprets as markup. Text visible in an editor disappears or changes style in the Viewer. The author separates literal prose from valid SMCL directives and tests the actual rendered help page. Links and section anchors are checked as well. A translation is not complete when the raw file looks correct; the interface delivered to readers is what matters. This example illustrates why ordinary punctuation and formatting tokens require different treatment in Stata documentation.
An error is styled but hidden by quiet execution
An author attempts to localize an error using a display string with an SMCL formatting directive and assumes it behaves exactly like display as error. In a quiet workflow, the expected message does not appear as intended. The team reviews the command’s actual error-display semantics and tests quiet and ordinary execution separately. The corrected diagnostic remains clear to users without manipulating the statistical result. Technical reviewers verify that a genuine failure is not mistaken for success because its human wording was translated.
A log accidentally includes identifiable records
A team demonstrates a validation failure by echoing the full command line containing a private file path and a participant identifier. That output is saved in a log and later shared for support. The documentation is revised to use fictional variables and a minimal error category that does not expose sensitive data. Translation reviewers still receive enough context to understand the intended message. This is a reminder that log files, screenshots and copyable commands can be disclosure surfaces even when the project itself is educational.
A historical ado-file uses older language features
A researcher inherits a community command written for an older Stata release. Its syntax declaration or help conventions differ from a recent tutorial. Rather than claiming every translation fault is a coding error, the team records the release under which the program works and the features it relies on. It chooses an appropriate version declaration and tests examples in the supported environment. This avoids teaching a fictional universal syntax and makes it easier for international colleagues to reproduce the historical analysis.
A right-to-left research note mixes code and prose
An Arabic-language help page includes Latin option names, percentages, parentheses and variable identifiers. On screen, the visual reading order can be confusing even though the stored characters are correct. Editors place commands in distinct blocks, keep the identifiers literal and review the Stata Viewer as well as copied code. They do not alter the statistical formulas merely to improve visual alignment. The result is a readable explanation whose command examples remain executable and whose numeric meaning can be checked independently.
An English abbreviation conceals an important definition
A table labels a statistic ‘SE’. A translator knows several possible meanings but not which applies to the program’s output. The author supplies context: standard error of an estimate, its units and its relation to the reported coefficient. A suitable translation is then chosen and added to the glossary. The result name used by downstream code is unchanged. This example shows the value of asking what a measure means before selecting a phrase that only appears familiar in another language.
Two language versions have different sample counts
A quality-assurance run finds that a translated example reports a different number of observations from its English counterpart. Rather than accepting the discrepancy as a locale issue, the analyst compares the actual commands and finds a changed sample qualifier. Restoring the command makes the results match. The translated explanation is retained because it was linguistically sound. Separating computation tests from language tests prevents a valid translation from disguising an invalid methodological example.
A machine reader depends on English log text
A reporting script searches a Stata log for a fixed English phrase and stops working when the same message is translated. The team recognizes that narrative text should not be a hidden machine interface. It redesigns the integration around stable returned results, numeric indicators or another documented structured contract. Human messages can then vary naturally by language without breaking the downstream workflow. Both locale choices are tested against the same synthetic calculation and machine consumer.
A university shares an ado package with partners
An academic department prepares a small ado program for collaborators abroad. It includes the program, companion help file, tested Stata versions, a synthetic sample dataset, example commands, message glossary and known limitations. Partners review the code and localized documentation separately. When a colleague finds a missing translation, the team can fix the human text without changing the estimation procedure or protected results. This explicit handover lowers support costs and protects reproducibility as staff and languages change.
Frequently asked questions
What is an ado-file?
An ado-file is a common way to define a user-written Stata command. The command’s name, executable syntax and help should be kept consistent.
What does syntax do inside a program?
It parses the user-supplied arguments and options according to the declaration. Translate the explanation of that grammar, not the keywords Stata executes.
Can a help file translate option names automatically?
No. An alias must actually be supported by program code. A local-language description does not add new executable keywords.
Why is the comma important?
Many Stata commands separate core arguments from options with a comma. Copyable examples should preserve punctuation required by the documented command.
Is a variable label the same as a variable name?
No. A label describes a variable for readers; a variable name is an identifier that code can reference. Show both in context.
What is SMCL?
Stata Markup and Control Language formats help and other output. It has directives that should not be edited as ordinary translated words.
Why can text inside braces disappear?
Stata may interpret particular brace patterns as SMCL directives. Test the rendered help, not only the raw source.
What is a .sthlp file?
A Stata help-file format for user-facing command documentation, typically including syntax, options, examples and links.
Should I translate display as error?
Translate the message presented to users, but keep the correct command behavior and error-display semantics.
Can Unicode text be displayed in logs?
Stata supports Unicode features, but test the actual release, environment, output format and fonts for the writing systems you need.
Why should I pin a Stata version?
Code and behavior may vary across releases. A version anchor documents the environment in which an example is meant to be reproduced.
Can I change variable names for a translation?
Do not change identifiers casually; that can break programs or refer to different data. Translate explanatory labels and document literal names.
Do translated tables need statistical review?
Yes. A fluent label can still misstate the statistic, unit or sample. Involve a subject specialist and compare results.
Is a translated log equivalent to the original audit trail?
Not necessarily. Preserve the original analytical record when reproducibility or an automated consumer depends on it.
What should a beginner test first?
A harmless custom command using a fictional string label, followed by missing and valid option cases. Avoid private datasets.
What defines a ready multilingual command?
Correct parser behavior, accurate help and messages, stable results, tested Unicode and a documented reproducible environment.
Primary documentation and further reading
Stata’s official programming features overview describes ado programs, parsing, Unicode and SMCL. The Stata programming FAQs collect help on syntax, versions and sharing commands, while advanced programming course topics show the relationship between ado-files, syntax declarations and help files. For development comfort, the Do-file Editor overview explains syntax highlighting and related editing support. Consult the installed Stata help for syntax and smcl to verify behavior in your own release.
Final perspective
A reliable localized Stata command preserves the analysis while making its instructions understandable. Syntax declarations, variable names, option tokens, macro punctuation and returned results form a technical contract. Human messages, help explanations and reader-facing captions can be translated when reviewers keep that contract in view. Test with synthetic data, compare numerical outcomes, inspect the Stata Viewer and logs, and make failures actionable. That is how statistical software can travel across languages without losing scientific meaning.