Wolfram Language notebooks are comfortable places to explore expressions, but an international team often needs the same calculation to run quietly from a terminal, scheduled workflow or shared command-line script. This guide explains how to localize wolframscript command-line arguments, $ScriptCommandLine, messages, usage instructions and diagnostics while keeping executable Wolfram Language syntax intact. The aim is a portable, understandable interface that works with people rather than merely reproducing English strings in a different script.
If you need a WolframScript -file example, a safe way to read $ScriptCommandLine, a multilingual Wolfram Language CLI, Unicode input handling or translation of batch-script errors, begin by separating three layers: the shell passes argument strings, wolframscript decides how the Wolfram Language kernel is launched, and the script interprets user data. Confusing those layers creates errors that translation alone cannot repair. The documentation below explains each boundary and shows how to test it.
By the end, you will be able to design a read-only command that accepts an international label, reports understandable feedback, rejects unexpected input safely and preserves the exact technical command words users must type. The examples use disposable test values, not private notebooks or destructive file operations. They are suited to researchers, analysts, teachers, multilingual support teams and anyone turning a useful Wolfram Language calculation into a dependable command-line workflow.
Quick answer
- Run a saved script with
wolframscript -fileto teach predictable argument access. - Read script-oriented arguments from
$ScriptCommandLine, checking positions and length. - Translate user messages and explanatory prose; preserve Wolfram Language functions and command options.
- Validate untrusted input rather than evaluating arbitrary expressions.
- Test Unicode, quoting, output and fallback separately from mathematical correctness.
A safe first script: preview a label
(* Save this harmless text-only program as preview.wls. *)
args = Rest[$ScriptCommandLine];
If[Length[args] < 1,
Print["Usage: wolframscript -file preview.wls 'label'"];
Exit[2]
];
Print["Preview label: " <> First[args]];
(* A Unix-style shell invocation:
wolframscript -file preview.wls 'Résumé draft'
wolframscript -file preview.wls '東京'
*)This sample treats the first supplied value as text, makes no filesystem changes and rejects missing input before selecting the first element. It assumes the documented script-file route; users should verify the script name position in their environment. The single quotation marks shown in the illustrative commands are Unix-shell quoting, not Wolfram Language syntax.
Understand the script boundary
Start with the invocation route
A Wolfram Language script is not merely a notebook with a different filename. When launched with wolframscript, it executes without the ordinary notebook conversation of evaluation cells, formatted output and visible prompts. The process receives command-line arguments and runs code that must explicitly print useful results. Identify whether colleagues run a saved -file script, a -code expression or a -function invocation before translating their help.
In a reproducibility check, record the complete invocation with a harmless placeholder. Do not infer that arguments arrive identically across those routes. A support answer should say which route it tested, because the same text can be parsed by a different layer depending on how the command is invoked.
Read the meaning of $ScriptCommandLine
The built-in $ScriptCommandLine is a list of strings representing script-oriented command-line elements when a WolframScript mechanism launches the kernel. In a standard script-file example, its first element identifies the script, and subsequent elements are supplied values. It is generally empty in a normal interactive notebook session. Those details explain many reports that an example works in Terminal yet returns an empty list when pasted into a notebook.
Use Length[$ScriptCommandLine] before selecting positions. Teach learners that Wolfram Language lists begin at index one. Do not claim that an empty notebook result means the command has lost arguments; the invocation context may simply be different.
Do not confuse $CommandLine
The related $CommandLine variable reflects the complete kernel command line, whereas $ScriptCommandLine is meant for the script’s own invocation. That distinction is useful when the executable is configured with engine options. A translator who copies sample output from the wrong variable can accidentally include implementation flags in a user-facing usage message or misidentify the first application argument.
Keep a diagnostic mode that displays an anonymised summary of count and position without dumping private values. Compare the two variables in a throwaway environment, then document only the variable appropriate to the public script interface.
Treat the executable name as a fixed token
Wolframscript is a command name, not prose to translate. The options -file, -code, -function, -args and -signature are also executable interface syntax. Localize their explanation, but keep the typed tokens unchanged unless a separate wrapper deliberately introduces translated aliases. Readers must be able to paste a documented command without guessing which words are the original switches.
A French explanation can say ‘exécuter un fichier’ while displaying wolframscript -file preview.wls unchanged. A Japanese guide can explain options in Japanese without changing the flags. This small discipline prevents a surprising number of multilingual support incidents.
Explain script arguments as data
Command-line arguments arrive as strings, even when they look like integers, dates, file names or Wolfram expressions. The script decides whether to interpret them. Displaying a string and evaluating it are dramatically different operations. The first is useful for safe learning; the second can execute code or cause side effects depending on the expression.
Use a label such as ‘東京’ or ‘Résumé draft’ in your first example. Avoid ToExpression on uncontrolled command-line data. A script that expects a number should validate a narrow permitted format and use an appropriate conversion strategy rather than evaluating arbitrary mathematical text.
Avoid notebook-only assumptions
Notebooks can supply front-end features, dynamic objects, interactive dialogs and rich typesetting. Headless batch users may have only a terminal stream and an exit status. When instructions casually say ‘the result appears’, readers need to know whether that means a Print message, a file, the last evaluated expression or a front-end display.
For a first release, choose plain output with Print and show a full terminal invocation. Document separately any requirement for front-end capabilities, licensed kernels, authentication, internet access or cloud execution. Translation should not conceal an operational dependency.
Describe what success looks like
A successful multilingual CLI is not defined solely by a correctly translated greeting. It should receive the same arguments, perform the same computation, distinguish data from diagnostics, preserve the result, and communicate any failure in words appropriate to the audience. Success criteria belong in the guide before an elaborate example.
Compare two runs that differ only in message language. The computed result, option boundaries and exit conditions should remain consistent. If the behavior changes, investigate code, parsing or environment before blaming the translation catalogue.
Build a small, safe WolframScript interface
Create a read-only label inspector
A minimal teaching script can use $ScriptCommandLine to extract a human-supplied label and print it back. It does not need to import documents, write files, connect to a service or launch another process. That restraint makes localization defects easy to see. Students can vary accents, spaces, apostrophes and scripts without risking important data.
Start with the complete example below, save it as a plain text script and run it through wolframscript -file. Include the filename in demonstrations and explain why the script is a fixture rather than a finished production argument parser.
Check length before selection
Wolfram Language’s Part syntax uses one-based positions. A script that immediately accesses $ScriptCommandLine[[2]] assumes an argument exists. With no supplied value, that assumption can produce a low-level message instead of your clear ‘missing label’ instruction. A friendly program checks the list length first and chooses a deliberate response.
Show a zero-argument invocation in the teaching materials. A translated error should identify what is missing, give a valid command example and keep the user’s original values out of diagnostic logs whenever possible.
Keep user messages in one place
If usage instructions are scattered across conditionals, a localization reviewer may miss half of them. Establish one explicit message map for labels such as usage, missing value, invalid value, example and success. Keep keys stable in source code, and place language-specific text in a clearly reviewable collection. This is a design choice, not an automatic feature of wolframscript.
A message lookup should have a visible fallback when the requested language is unavailable. Reviewers must test both the available locale and the fallback, including when a translated entry is accidentally empty.
Separate language choice from business input
Consider a script that accepts a measurement and prints a report in a requested language. A language switch selects how feedback is expressed; it must not reinterpret the scientific measurement. In particular, changing decimal punctuation inside numeric input without a documented rule could alter values and undermine reproducibility.
Treat locale selection as an explicit option of an application wrapper or a validated data field. Do not reinterpret unlabelled values based on the operating system’s apparent locale if users depend on stable batch results.
Choose human vocabulary that is actionable
‘Invalid input’ rarely tells a newcomer enough. A useful message says which field failed and what accepted form looks like. For a text label, ‘Provide one nonempty label’ is clearer; for a positive count, ‘Enter a whole number greater than zero’ is more actionable. Translation must retain that level of specificity.
Create a bilingual message review in which one person understands Wolfram syntax and another knows the target language. Ask them independently what action the user would take after each error; mismatched answers expose ambiguities.
Treat help as a real user interface
A command’s help text may be the only interface available to a scheduled-job maintainer. It should explain purpose, syntax, positional values, examples, output and failure behavior. Avoid giant paragraphs that mix the executable command with the reason to run it. In localized manuals, put examples on separate lines so punctuation changes do not alter shell tokens.
Provide a compact first example using plain ASCII, then a Unicode example, and finally a missing-input example. Those three cases answer the largest number of beginner questions without requiring a complex framework.
Keep code and output distinct
A Wolfram Language demonstration includes shell commands, Wolfram code, and sample output. If the page does not label them, a reader may paste an output line into Terminal or treat shell quotation marks as part of the argument. Clear typography and introductory sentences prevent this confusion even when the article is read through machine translation.
Introduce each block with its role: save this as a script, run this in Terminal, expect an equivalent line on screen. Do not present illustrative output as a literal guarantee across every Wolfram environment.
Preserve syntax, types, and computation
Translate surrounding prose, not built-in symbols
Built-in function names and system symbols are identifiers. Translate the concepts behind Print, Length, Part, StringQ, Interpreter or If; do not alter their spelling inside executable examples. A reader may appreciate a local-language glossary for each symbol, but the code must remain runnable in Wolfram Language.
In a classroom handout, place the explanation alongside the original code token. For example, describe ‘list length’ in the learner’s language while leaving Length unchanged. This helps comprehension without inventing a dialect of Wolfram Language.
Distinguish strings from expressions
Text such as ‘2+2’ can be a string, an unevaluated expression or a computed numeric result. Those forms are not interchangeable. A command-line interface should declare whether it accepts words, numbers, expressions or file paths. Translating ‘expression’ as an ordinary ‘phrase’ may encourage a user to supply syntax that the script does not support.
For educational exercises, accept a display label rather than an expression. A production tool requiring mathematical expressions needs a separately designed parser and a threat model because arbitrary evaluation is not a harmless conversion.
Avoid unrestricted ToExpression
ToExpression is powerful precisely because it turns text into Wolfram Language expressions and can evaluate them. That makes it unsuitable as a generic way to parse arguments from unknown users. Even if your application expects a number, the safer pattern is to constrain the grammar and explicitly decide how to convert it.
Document a whitelist such as unsigned decimal digits or a bounded signed integer when appropriate. Test unexpected punctuation, whitespace, symbols and long strings. Reject untrusted expressions before they can reach executable evaluation.
Explain quoting at the shell layer
A shell often uses quoting to keep a space-containing label as one argument, but the precise quoting rules vary across Bash, Zsh, PowerShell, Command Prompt and other environments. Wolfram Language does not repair tokens already separated by the shell. Localized instructions should name the shell demonstrated and avoid claiming identical behavior everywhere.
Use a simple Unix-style example with a single-quoted label and label it accordingly. Add a separate Windows example only when tested in that Windows environment. Never translate quotation marks as typography in a copyable command.
Keep Unicode data unchanged
Wolfram Language can represent a wide range of Unicode text, but a terminal pipeline still has to transmit, display and log it correctly. There is a difference between the characters in an argument, the bytes used for transport, the terminal’s font and a later export encoding. A display problem does not automatically mean the string was corrupted.
Check the same value in an explicit string comparison and in terminal output. Use examples with composed accents, combining marks, CJK characters and right-to-left text. Record what remained equal and what merely looked different.
Respect the role of the locale
Locale changes can affect date display, sorting expectations, number formatting and natural-language strings. Yet a numeric research script often needs invariant serialized values so downstream computation is unaffected. Distinguish ‘show the number to a person’ from ‘pass the number to another program’. Mixing the two makes translation a data-integrity problem.
If a generated CSV or JSON file is part of the workflow, specify its invariant format separately from translated onscreen help. A visual decimal comma should not silently enter a machine-readable numeric field.
Be precise about list positions
Wolfram Language lists are indexed from one, and $ScriptCommandLine in a typical -file use places the script name at the front. The first user value is therefore commonly the second element. This matters when support teams adapt examples from languages whose array indices start at zero.
Demonstrate positions explicitly with a diagram or a small printed list. Verify the actual invocation used by the audience rather than hard-coding an index from an unrelated tutorial.
Run and explain different execution modes
Understand the -file route
The -file option runs code from a supplied file. It is well suited to teaching because a reader can inspect and preserve a stable script artifact. Document the installed WolframScript version and how the Wolfram Engine is configured. Translate a wrapper’s prose but leave the -file option and the file’s actual path untouched.
A handout should include a safe relative filename and a sentence explaining the current working directory. Many apparent translation failures are simply caused by running the command somewhere the example file does not exist.
Use -code for narrow demonstrations
The -code option executes a string of Wolfram Language code passed as an argument. This is useful for short comparisons, but it adds an extra layer of shell quoting around source code. More complicated translated examples become harder to reproduce when prose editors replace ordinary quotes or escape characters.
Prefer -file for a full localized program and -code for a one-line conceptual test. Never construct code strings by concatenating an untrusted natural-language input merely to avoid writing a file.
Recognize the -function mode
WolframScript also supports a -function form with argument interpretation and optional signatures. It is a different interface from reading a script file’s $ScriptCommandLine list directly. A tutorial should not borrow argument positions or parsing rules from a -function example and apply them to -file without explanation.
When helping a user, ask which literal option appears in the command and reproduce that path with disposable inputs. Keep the public API documentation separate from teaching examples so readers know which contract they are following.
Understand local and cloud execution
WolframScript can work with local or cloud execution according to configuration and selected options. A cloud context may introduce authentication, network access, data-residency requirements and different availability of local files. Translation should make those dependencies visible rather than implying all scripts behave the same everywhere.
Show the tested execution context in a prerequisites paragraph. If a research group handles confidential records, explain where computation and data are performed and do not recommend cloud upload as a casual troubleshooting step.
Handle standard input separately
The built-in $ScriptInputString relates to data supplied through standard input, not simply an alias for positional command-line arguments. Someone piping a paragraph to a script may need a different design than a user providing a short label after a filename. Treating these routes as identical can consume the wrong input.
Describe whether the tool takes a short argument, piped text, a file path or a combination. Keep the roles consistent in translated help so a user does not accidentally place private document content directly on the command line.
Manage output deliberately
Print produces visible text that a terminal can capture. A returned expression or a notebook-style formatted result is not necessarily presented in the same way during batch execution. Decide whether output is meant for people or another program and identify the exact lines a script promises to emit.
For a machine-readable mode, avoid friendly translated introductions mixed into the data stream. For human mode, explain success in simple language. This separation makes localization simpler, not merely prettier.
Make failures visible without secrets
An exception or evaluation message may contain expressions, paths or user-provided values. Copying it into a translated support report can disclose information the user did not intend to share. Good diagnostics identify the failed operation and give a safe next step without reproducing sensitive data unnecessarily.
Keep detailed private logs behind appropriate controls and redact inputs in public examples. A translated support document can use an invented path, a fake sample label and a generic job identifier to demonstrate the same fault.
International quality assurance and deployment
Build a language test matrix
A multilingual script deserves tests that combine language, argument shape and operating environment. Test English plus target locales with empty values, quoted spaces, accents, CJK text, right-to-left characters and unrecognised options. Include the actual shell and engine versions rather than a vague statement that Unicode was tested.
Create separate columns for expected parsing, expected computation and expected display. This distinguishes a correct string that the console draws poorly from a real misinterpretation of the argument.
Check copy-and-paste fidelity
Some content systems automatically replace straight quotation marks with typographic ones, fold whitespace or introduce invisible characters. In shell code, such editorial changes can alter how arguments are grouped. International documentation is particularly exposed because translators may use writing software designed for prose rather than commands.
After publishing, copy each command from the rendered page into the tested terminal. Compare its bytes with the source version. Fix the content, not the reader, if a harmless quote was converted into incompatible punctuation.
Test bidirectional display
Arabic and Hebrew can display alongside Latin function names, numeric values and punctuation. The visual reading order may differ from storage order, particularly in terminals and copied code blocks. Never judge an argument’s exact contents solely by how one terminal renders it.
Use code fences for executable tokens and clear labels outside them. For official audit records, compare stored values rather than relying on screenshots of mixed-direction text.
Check normalisation-sensitive comparisons
The same visible accented word may use a precomposed code point or a base letter plus combining mark. String comparison and downstream matching may treat those differently unless the application intentionally normalizes. Translation teams should know whether labels are display-only or machine keys.
Use a harmless name such as café in both Unicode compositions and compare intended behavior. If normalization is required, document the policy explicitly and ensure identifiers or legally significant names are not changed unexpectedly.
Design fallback before shipping
The default language should be a documented, complete path, not an accidental mixture of half-translated strings. If a locale is unavailable, the script can fall back to an established language while preserving predictable exit codes and data outputs. Users deserve to know when a fallback occurred.
Test an unsupported locale code and a missing translation entry. An implementation that prints an empty success message is not a graceful fallback even if the calculation itself was correct.
Keep translation review separate from code review
A reviewer fluent in the language may not know whether ‘kernel’, ‘evaluation’, ‘argument’ and ‘expression’ have specific computational meanings. A developer may overlook whether the translated sentence is natural or actionable. Both kinds of expertise are necessary for reliable educational software.
Ask reviewers to resolve a small real task with only the translated help. Record misunderstandings, then verify that the amended prose preserves the program’s technical contract.
Document environment assumptions
A command that succeeds on one laptop may rely on a configured Wolfram Engine, an authenticated session, a working license, an available local script or an accessible cloud resource. These are not translation problems, although they often surface while testing translated guides.
List prerequisites near the first runnable example and state what a reader should check when the executable is missing or cannot launch. Avoid publishing secret configuration paths or credentials.
Worked examples, decisions, and handover
A university distributes a numerical helper
A teaching assistant wants students in several countries to run an identical calculation. She keeps the formula and serialized result constant, but localizes the usage explanation, argument description and human-readable confirmation. Students first run a simple label inspector, then a validated numeric fixture. This gradual approach makes it obvious which part changed and protects reproducibility.
The release checklist has separate approvals for numerical equivalence and translated guidance. A disagreement about decimal notation is resolved by keeping the machine result invariant and offering locale-aware explanatory text only in human mode.
A research assistant receives an expression
Someone sends a command suggesting a convenient ToExpression conversion of whatever the user types. The review identifies that the command line is not a trusted notebook cell. It replaces free-form evaluation with a limited input contract and adds an error that names the accepted numeric form. The change is explained without teaching a risky expression-evaluation pattern.
The localized documentation illustrates a rejected expression and a successful ordinary value using fictional data. The help explains why rejection is a safeguard, not a failure of Wolfram Language to understand mathematics.
A Windows colleague cannot reproduce quoting
A colleague copies a Unix shell command with single quotes into a different command interpreter. The script sees an unexpected argument shape. Rather than translating the options again, the maintainer identifies the shell mismatch and supplies a separately tested invocation for that environment.
The support note distinguishes syntax required by the shell from the $ScriptCommandLine representation inside Wolfram Language. It asks for a redacted argument count instead of a screenshot containing personal files.
A notebook produces an empty argument list
A student pastes $ScriptCommandLine into a notebook and sees an empty list, even though the instructor’s batch example reports values. The instructor explains that the variable describes script invocation and the notebook session is a different execution context. The correct experiment uses a saved script launched through wolframscript.
This example matters because it teaches how to compare environments before changing code. Translating the error message alone would not solve the underlying conceptual misunderstanding.
An Arabic team reviews a mixed-language command
A bilingual operations team needs Arabic explanations around Latin options and numeric diagnostics. Its first help page visually reverses punctuation near -file. The revision separates narrative text from copyable command blocks and tests the rendered page in the systems users actually run.
The lesson is not to avoid Arabic or any other right-to-left language. It is to preserve exact executable tokens while giving the surrounding explanation enough typographic structure to remain readable.
A scripted pipeline consumes friendly output
An automated report reader expects one value per line. A new localization adds a welcome sentence ahead of the number, breaking the parser. The team separates stable data output from human diagnostics and updates the documentation to identify which stream has which purpose.
A regression test verifies the literal machine output across languages. The more conversational output is available only when requested, so human warmth no longer modifies downstream data.
An unsupported locale appears in a job
A nightly batch job requests a locale for which there is no complete message set. Previously the script returned blank text. The revised application logs a safe fallback notice, uses a complete supported language, preserves the result and marks the locale-selection problem separately.
Reviewers verify what happens if one message key is absent even in a normally supported locale. This avoids silent holes that a simple language picker test would miss.
A team packages a script for a partner
The partner needs to know not only which file to run, but what versions, license or configuration, locales and inputs were tested. The team distributes a short quickstart, a message glossary, harmless sample commands and a troubleshooting map that distinguishes launch, parsing, calculation and display failures.
The handover records a contact for technical issues and another for translation questions. That division prevents linguistic edits from being mistaken for permission to change mathematical methods.
Frequently asked questions
Does $ScriptCommandLine work inside a normal notebook?
It is designed for script invocation. In a normal interactive notebook session it can be empty. Test a saved script launched through wolframscript before concluding arguments are missing.
Why does [[2]] represent the first user argument?
In a typical wolframscript -file invocation, the list includes the script name first. Wolfram Language positions are one-based. Always check the actual list shape and length in your target execution route.
Can I translate -file and -code?
Translate their explanations, not the literal option tokens. Command names are executable syntax. Inventing a localized spelling would require a separate wrapper that explicitly recognizes it.
How can I safely parse numeric input?
Define an accepted numeric grammar, validate length, sign and allowed characters, then convert through a reviewed path. Never treat arbitrary untrusted command-line text as Wolfram code to be evaluated.
Why did ToExpression raise a security concern?
It interprets text as expressions, which may have computational or side effects. Parsing a number from an unknown user is a narrower job than evaluating a complete Wolfram Language expression.
What is the difference between $CommandLine and $ScriptCommandLine?
The first describes the complete command-line environment; the second focuses on arguments provided for the script mechanism. Do not infer positional indexes in one from a demonstration of the other.
Is -function the same as -file?
No. They represent different WolframScript execution modes with different ways to expose supplied values. Keep examples and their assumptions attached to the mode they actually demonstrate.
How do I explain Unicode without claiming a perfect display?
Separate data preservation from terminal rendering. Test exact string values, the font and terminal behavior, and the exported file encoding when one exists.
Should I translate machine-readable output?
Usually keep a stable documented machine format and localize messages intended for humans. Otherwise an innocent language preference can break a downstream parser or data import.
What should the first troubleshooting command do?
Use a harmless inspection script that reports argument count and a made-up label. Avoid destructive file operations or printing confidential command-line values into public logs.
How should I present examples for Windows and Unix?
Show the actual shell and its tested quoting rules. Never imply that a single quoting example is portable to every command interpreter.
When is a language fallback acceptable?
When it is explicit, complete and predictable. A user should not receive an empty error or a mixture of misleading partial strings just because a locale is unavailable.
What should a translation glossary include?
Pair terms such as argument, expression, kernel, script, evaluation, input, output and diagnostic with context. Distinguish everyday meanings from technical ones.
Can a cloud execution example use local paths?
Only when that execution environment actually has access to those paths. Cloud and local contexts differ in resources, configuration and data controls. State assumptions rather than promising equivalence.
Is an interactive notebook result the same as Print output?
No. A notebook may format evaluation results interactively; a batch script should explicitly produce the output its consumers rely on.
What is the release criterion for a multilingual script?
Its executable syntax, validated inputs, computation, exit behavior and machine results should remain correct across supported language choices, and human messages should be clear in real usage tests.
Primary documentation and further reading
Consult Wolfram Research’s WolframScript reference, the $ScriptCommandLine reference, the Create Wolfram Language Scripts workflow and $ScriptInputString documentation. Each documents a different part of the route from invocation to data, and the exact Wolfram version in use remains relevant.
For a related comparison of argument boundaries in another numerical language, read MATLAB inputParser localization and GNU Octave inputParser localization. These are neighboring lessons, not replacements for WolframScript’s own script-argument model.
Final perspective
A high-quality translated WolframScript command does more than replace English labels. It helps people understand which text belongs to the shell, which tokens are fixed Wolfram options, which strings are arguments, what the script will compute and how to recover when something goes wrong. Test those boundaries with disposable data, protect the executable grammar and make every human message useful. That is how a small script becomes reliable for readers working across countries and languages.