AppleScript automations often start with a simple promise: do a repetitive task with fewer clicks. When someone needs to run that automation from Terminal or share it with colleagues in another language, the promise becomes more demanding. This complete guide explains how to localize AppleScript osascript messages, on run argv parameters, usage examples and safe diagnostics without changing the script invocation or accidentally automating the wrong application.
If you are searching for an osascript command-line example, AppleScript on run argv, osascript -e, shell quoting, localized string, handling Unicode text or translating AppleScript errors, the most useful first distinction is between the shell, osascript and the script’s own handler. Each layer interprets something different. A translation that changes the wrong layer can make an apparently familiar example fail or, worse, run an unintended automation.
Begin with a read-only script that accepts a harmless label and returns a message. Then explore how arguments arrive, how errors are routed, how AppleScript interacts with macOS applications and which user-facing words you can translate safely. This guide is aimed at international support teams, Mac users, educators and developers who need reproducible explanations rather than scripts that rely on private files or destructive commands.
Quick answer
- Use a saved AppleScript with on run argv for the clearest argument examples.
- Keep shell quoting, osascript options and AppleScript handler logic separate.
- Translate controlled user messages, not the syntax of AppleScript or target app commands.
- Test empty input, Unicode, errors and permissions before automating real tasks.
- Use safe fixtures and reproduce commands in the stated macOS and shell environment.
Read-only AppleScript argument inspector
-- Save as preview.applescript. The script only returns a string.
on run argv
if (count of argv) is 0 then
return "Usage: osascript preview.applescript 'label'"
end if
set firstLabel to item 1 of argv
return "Preview label: " & firstLabel
end run
-- In Terminal:
-- osascript preview.applescript 'Résumé draft'
-- osascript preview.applescript '東京'The sample reports only a disposable label. It does not read or change a file, control another app, invoke a shell from AppleScript or ask for private permissions. Save the script before invoking it with osascript, and test in a supported macOS Terminal. The translated usage message belongs to your application; it does not redefine the osascript command or the on run handler.
Follow an argument from the shell to the run handler
A Terminal command can look like a single sentence, but its components belong to different interpreters. The shell handles quoting, token boundaries and expansion; osascript selects the script source and scripting language; AppleScript’s explicit run handler can receive a list of supplied strings. Apple’s AppleScript Language Guide explains run handlers and the osascript manual documents file-based argument passing. Learning this route makes multilingual troubleshooting substantially easier because it locates the point where a mismatch arose.
Understand the role of osascript
osascript executes Open Scripting Architecture scripts and accepts program files or inline statements.
A reader may think the command itself is a translation engine or a generic shell parser.
Explain what osascript launches before describing any application-owned usage words or translated output.
Prefer a saved script for argument examples
A script stored in a .applescript or compiled script file provides a clear source boundary for arguments that follow its filename.
An example relying on nested -e quoting can obscure which tokens belong to the script.
Start with a small saved file, then call it from Terminal using two disposable labels.
Use an explicit on run argv handler
An explicit on run argv handler can receive the arguments passed after the script name as a list of strings.
A tutorial that expects a single plain text value instead of a list will misread multiple arguments.
Return the number of items and the first item in a harmless inspector before accepting complex values.
Check the zero-argument case
A script invoked without a user argument can receive an empty list.
Reading item 1 immediately without checking count can produce an error before the user sees useful guidance.
Return a clear usage message when count is zero, then test exactly that invocation.
Index AppleScript lists from one
Items in an AppleScript list are commonly addressed as item 1, item 2 and so forth.
Copying a zero-based indexing habit from another language can make the first argument example invalid.
Supply two known values and verify that item 1 and item 2 are reported in the expected order.
Remember that arguments are strings
The osascript manual describes parameters passed to run as a list of strings; conversion is the script’s responsibility.
A numeric-looking argument may still be text when the handler begins.
Check the source text before conversion and test a nonnumeric value separately from a valid numeric one.
Quoting belongs to the shell
A quoted label containing spaces is generally delivered as one argument after the shell processes its quotes.
Replacing straight shell quotation marks with typographic ones can split a path unexpectedly.
Run the example with a two-word label and compare it with the same words supplied unquoted.
Do not assume shell expansion is harmless
Variables, wildcards and substitutions can change the arguments before osascript sees them.
An unquoted wildcard in a guide may expand to private filenames from a reader’s working directory.
Use literal safe examples and show how to quote values before they enter the command.
Separate script filename from user data
The script path tells osascript what to run; later tokens are supplied to its run handler.
A guide that treats the script filename as argv item 1 shifts every positional explanation.
Show a labeled command diagram distinguishing the launcher, script and supplied arguments.
Avoid claiming portable shell syntax
Terminal examples on macOS often use zsh or another Unix-style shell, not Windows Command Prompt semantics.
A world-facing guide that silently assumes the same quoting rules everywhere may be impossible to follow.
State the tested shell and macOS context, then adapt examples deliberately for other supported environments.
Translate user messages without changing executable behavior
AppleScript is built around controlling applications and using commands with precise meanings. The language a person sees in a help panel, dialog or return message is a different layer from the language of AppleScript syntax. The AppleScript Language Guide describes a localized string command, but an application also needs a properly packaged localization strategy and correct resources. Avoid claiming that a single function call automatically turns every script and external application into a translated product.
Keep handler names as code
The run handler has language-defined meaning and must be written with valid AppleScript syntax.
Replacing on run with a natural-language equivalent is not localization; it creates invalid source.
Translate the explanation of the handler, not the keyword that makes it execute.
Translate return messages deliberately
A script can return an application-owned message such as Preview completed or No label supplied.
An editor might translate the message but also alter the script’s argument recognition logic.
Keep parsing independent from message selection and compare the returned structured meaning across languages.
Use localized string in context
AppleScript provides localized string for obtaining localized content where the appropriate localization resources exist.
The command does not guarantee that arbitrary English text will be translated without prepared resources.
Check the bundle and lookup behavior on each supported macOS release, including fallback results.
Distinguish dialog from CLI output
display dialog is a graphical user interaction, while return values from osascript can appear in Terminal.
A script intended for headless automation may unexpectedly block while waiting for a localized dialog.
Choose the interaction channel intentionally and run command-line tests without requiring a click.
Do not localize Apple events blindly
AppleScript commands target specific scriptable applications through their dictionaries and event interfaces.
Changing an application command as if it were a translated sentence can break the target operation.
Preserve tested application terminology in executable code and localize separate guidance for the user.
Preserve paths and file identities
A file name in a script may identify a real resource and is not a sentence to paraphrase.
Translating path segments in a tutorial can silently direct the script to a nonexistent location.
Use disposable test paths and explain clearly where a reader must substitute a local file.
Use clear parameter vocabulary
Words like script, parameter, handler, application and event should remain distinguishable in every language.
A vague translation of parameter as command may cause the reader to pass an option in the wrong position.
Include a simple command diagram alongside an example showing precisely which text becomes argv data.
Keep formatting tokens under control
Quotes, backslashes and line continuations can be significant inside shell and AppleScript examples.
Publisher typography may introduce punctuation that looks similar but changes parsing.
Store executable examples as literal code and repeat copy-paste tests from the published page.
Review bidirectional text display
Right-to-left commentary can surround left-to-right command tokens in a way that makes punctuation hard to read.
A visually correct screenshot may conceal an incorrect copied command order.
Test both rendering and literal text selection with the target language edition.
Choose a tested language fallback
A message catalog may lack a translation for a less common language or a new error.
Displaying an empty string or an unrelated message leaves users unable to recover.
Define a sensible fallback language and report missing resources during release review.
Use errors, streams and shell boundaries safely
A script invoked from Terminal has several observable outputs: return text, standard error, and a process outcome. An automation that manipulates applications may also produce user-visible dialogs or external effects. These channels should not be confused. The safest examples use read-only argument inspection, and any real automation should check its permissions and errors before changing files. Accurate translation makes the boundary between a wrong invocation and a failed application action visible.
Understand osascript -e
The -e option supplies an inline script statement, with multiple -e options available for additional lines.
Nested shell quoting and AppleScript quoting can make inline examples difficult to copy reliably.
Use file-based scripts for long tutorials and reserve -e for small, clearly quoted examples.
Understand osascript -l
The -l option selects an installed OSA scripting language rather than a natural-language locale.
A guide that treats -l fr as ‘French messages’ invents behavior the option does not provide.
Explain scripting-language selection separately from application-owned message localization.
Understand osascript -s output controls
The manual describes -s flags affecting how results and errors are displayed.
A translated result with a different display format may confuse scripts that parse output mechanically.
Check the documented flags and capture actual output before promising a machine-readable format.
Keep errors off data streams
Script errors are generally routed to stderr under the documented default behavior.
If an error is merged with stdout, a downstream tool may parse it as legitimate data.
Capture stdout and stderr separately and show what happens when the handler fails deliberately.
Avoid treating display text as structured data
Human-readable osascript results may omit details such as quotes and nested structure boundaries.
A script that parses those messages as a reliable data format can misread certain lists.
Use a deliberately designed structured protocol when other programs need machine-readable results.
Protect shell arguments from injection
An argument passed to AppleScript is data until a later script builds and executes a shell command from it.
Concatenating untrusted values into do shell script creates risks unrelated to translation.
Avoid execution in a tutorial; if real code must use a shell, quote and validate arguments for that boundary.
Know that do shell script is separate
The AppleScript do shell script command invokes shell behavior from within the script and is not synonymous with osascript.
A translated tutorial that conflates the two directions makes debugging both security and quoting difficult.
Draw the two possible process flows and identify which command creates a new shell.
Minimize application permissions
Automations that control Finder or other apps can require operating-system permissions that are not part of argv parsing.
A working argument inspector does not prove the full automation has access to protected application data.
Test parsing separately, then test permissions using deliberately safe application actions.
Preserve original error context
Replacing every failure with one translated sentence may hide which application or handler failed.
Support teams need specific error categories to distinguish syntax mistakes from authorization problems.
Retain useful diagnostic context and add a human explanation only for well-understood cases.
Make safe failure the default
A missing or malformed value should not cause a script to fall back to an arbitrary real file or target app.
In multilingual instructions, misunderstanding one parameter can otherwise trigger unintended operations.
Validate before acting, return a clear usage message and verify that the failure path changes nothing.
Test multilingual AppleScript automations before sharing them
A translation is dependable only when another person can reproduce the behavior in the actual environment. macOS versions, installed application dictionaries, locale resources, Terminal fonts and shell settings affect what a user experiences. There is no substitute for small test cases covering success, failure, non-English data and permission boundaries. These checks should be performed on disposable inputs rather than a colleague’s genuine documents or private account.
Record tested macOS versions
AppleScript features and application automation behavior can differ between platform releases.
A guide that implies timeless compatibility may mislead users whose installation lacks a required feature.
State a tested macOS and shell combination and verify the installed osascript help.
Use a read-only inspector first
A script that only returns the argument count and a harmless label helps isolate parsing problems.
A tutorial that immediately moves files makes every mistake more expensive to diagnose.
Require a clean inspector run before adding file, mail, calendar or application actions.
Test a missing argument
The simplest failure is an invocation without the required user value.
If the script crashes on item 1 before explaining usage, the translated help never reaches the reader.
Run the command with no trailing arguments and verify the intended instructional result.
Test spaces in values
A file name or label with spaces exposes shell quoting problems that ASCII single-word examples miss.
People may report ‘wrong translation’ when the actual failure is a split argument.
Compare quoted and unquoted invocations and record the argv count for each.
Test accented and CJK data
An argument can include accented or non-Latin characters even though the handler structure stays the same.
A terminal or downstream program may fail to preserve characters that the script initially received.
Use harmless multilingual labels and check exact output rather than visual resemblance alone.
Test right-to-left text
Arabic and Hebrew values can expose directional display problems when mixed with Latin program names.
Readers may mistake the visual position of punctuation for the logical token boundary.
Capture the actual text, copy it into a trusted editor and compare the underlying characters.
Inspect stdout and stderr
A user can redirect returned text into another command, making accidental diagnostic output significant.
A translated message printed on the wrong stream may corrupt a data pipeline.
Run successful and failing cases while capturing each stream independently.
Review privacy in diagnostics
A script may display real filenames, email addresses or document titles when users post an error report.
Translation does not remove the privacy risk of copying those values into shared channels.
Offer a reproducible report using fake labels and redact personal information from screenshots.
Test application permissions separately
A script that parses argv may still fail to control a protected macOS application.
An error about permissions should not be described as a bad argument or a translation problem.
Identify the target app and reproduce a permission-denied case without modifying production data.
Package the localized assets
Message resources, scripts, instructions and tests must all accompany the distributed automation.
A developer’s machine may contain assets that are missing from a teammate’s shared zip file.
Perform a clean-install test in each supported language and verify fallback behavior.
Worked situations in international AppleScript support
Many real problems labeled translation errors are actually quoting mistakes, indexing mistakes, missing permissions or confusion about the launch process. These short cases connect a user’s complaint to the layer responsible and to a safe reproduction. They are useful both for a support agent reading a ticket and for a technical writer creating the next version of a guide.
A bilingual office uses a label script
A Mac office wants a short Terminal script to print a label in English or Chinese for use in a document workflow.
Keep argv position and shell syntax fixed while selecting an application-owned label based on a documented locale setting.
Run the same harmless label through both languages and compare the received text before changing documents.
A command contains a quoted space
A colleague runs osascript preview.applescript ‘new report’ and expects one label argument.
Explain that the shell keeps the quoted words as one token and that the script does not receive the quote marks themselves.
Return count of argv and item 1, then compare with an invocation containing two unquoted words.
A script uses item zero
A programmer familiar with JavaScript attempts to read item 0 of argv as the first supplied value.
Teach AppleScript list indexing with item 1 and demonstrate how the first value is retrieved.
Use two distinct dummy tokens to verify both positions rather than relying on a single value.
A translated command changes on run
A well-meaning translator rewrites the words on run into the local language while editing a code example.
Restore the executable AppleScript handler syntax and put the translated explanation outside the code block.
Compile or execute the original and edited examples to reveal the syntax boundary.
A support document recommends -l fr
A reader assumes osascript -l is a French language selector and reports that the script still prints English.
Explain that the option selects the OSA scripting language, not the natural language of messages.
Inspect the installed scripting languages and test localization through explicit application resources instead.
A UI dialog blocks a scheduled job
A script displays a translated modal dialog during an unattended nightly run.
Move headless status reporting to an appropriate noninteractive channel and reserve dialogs for intentional interactive workflows.
Run the command in a test environment without interacting with the screen and verify that it completes.
A user passes a path starting with a dash
A path or label begins with punctuation that resembles an osascript option in the launcher invocation.
Clarify the division between launcher options, script filename and data arguments before publishing example commands.
Inspect received tokens using a disposable path rather than opening the target resource.
A word processor modifies quotation
A multilingual handout changes straight single quotation marks to typographic punctuation around the Terminal example.
Publish a copyable plain-text command and explain why typography should not be edited in runnable snippets.
Copy the displayed command into a supported shell and inspect the handler’s received count.
An app lacks automation permission
The argument inspector succeeds, but a script that controls a target macOS application is denied access.
Separate invocation correctness from operating-system authorization and give a safe, specific explanation.
Verify a permission error with a deliberately harmless operation rather than retrying a destructive action.
An Arabic guide mixes writing directions
The sentence surrounding a Terminal command is right-to-left while the quoted script filename is left-to-right.
Present commands in isolated code blocks and keep a readable explanation in the page’s prose direction.
Select the code, paste it and compare token order, not simply visual alignment.
A diagnostic leaks private information
A failure message includes a confidential filename in a screenshot uploaded to a shared forum.
Replace the real path with a dummy fixture and record only enough error context to reproduce the category.
Confirm that the technical issue persists after redaction and remove identifying details before publishing.
A packaged script misses translations
A developer’s own machine displays localized text correctly, but another Mac falls back to an unexpected message.
Review packaging of the localization resources and how localized string resolves in the actual bundle.
Test a clean installation with two supported languages and an unavailable locale to document fallback.
Further training, review and safe deployment
A reader’s mental model
Imagine three doors in sequence. The shell decides how typed words become tokens. osascript decides which script or OSA language to run. The AppleScript run handler decides what those supplied strings mean to the application. When an error appears, identify which door produced it before rewriting instructions. This model is more reliable than translating every visible word as though it came from one parser.
A documentation inventory
Create a table containing the exact osascript command, selected script file, expected argv count, required arguments, owned user messages and error channel. Mark which elements are stable technical syntax and which can be localized. For each translatable sentence, provide the context that triggers it so reviewers can select a natural and accurate wording.
A safe classroom sequence
Have students create a script that returns the number of arguments. Next, return item 1 after checking for emptiness. Then pass two labels with and without quotation marks. Only after the behavior is understood should students translate one usage sentence into a second language. Avoid using an automation that sends messages or modifies files as the first exercise.
A release test matrix
Prepare tests for no arguments, one argument, two arguments, whitespace, punctuation, accented text, CJK text, right-to-left text and an intentional error. For each case, capture the exact invocation, script return, stdout, stderr and whether any application action occurred. The same matrix can be rerun after macOS or script updates.
Message ownership
The shell, osascript, AppleScript runtime and a controlled application can each contribute diagnostic wording. A translation project should not claim ownership of strings generated by other components without verifying they can be changed. Instead, add a clear explanatory wrapper for known failures and preserve lower-level error context when it is needed for debugging.
Do not hide permissions
macOS automation privacy controls exist independently of script localization. Users may have to grant authorization to control a particular app, and the requirements can vary by deployment. Explain why the action needs access, avoid asking for broad permissions without need and never treat a permission denial as an input-language error.
Protect executable examples
Keep shell commands and AppleScript source as separate copyable code blocks. State the tested shell, label all placeholders and avoid smart punctuation. When adapting a guide to a new language, check that the displayed quotation marks, filename extensions and whitespace boundaries still produce the intended invocation.
A practical glossary
Translate terms such as script file, handler, argument, list item, shell, return value, standard error and application permissions with care. Short examples prevent confusion: ‘argument’ should refer to the value passed to argv, while ‘handler’ describes the code that processes it. An exact context matters more than a dictionary equivalent.
When to seek specialist review
If an AppleScript automation can delete data, access messages, change settings or control external systems, a successful translation review is not enough. Have the script owner review what each argument permits, set safe defaults and test failure paths. A readable help message is useful, but it does not establish that the underlying operation is safe.
Next learning exercise
Build a read-only greeting script with a chosen display label and a second optional language code. Add clear usage output for a missing label. Have a language reviewer inspect two translated messages while a technical reviewer verifies that both paths receive the same argv values and have no external side effects.
Frequently asked questions
How do I pass command-line arguments to AppleScript?
Save a script with an explicit on run argv handler and invoke it through osascript followed by the script filename and the desired arguments. The handler receives a list of strings. The shell processes quoting first, so wrap a value containing spaces appropriately for the shell you use.
Why does item 1 of argv fail?
The list may be empty if no user arguments were provided. Check count of argv before reading an item. The first supplied value is addressed as item 1, not item 0. Provide a clear usage message for the empty case rather than relying on an unhelpful runtime failure.
Does osascript -l select French or Japanese text?
No. The -l option selects an installed OSA scripting language such as AppleScript where available. It is not an ordinary natural-language translation setting. Localize application-owned messages through an explicit design and any appropriate resources, keeping the launcher option meaning intact.
When should I use -e?
The -e option supplies an inline statement and is useful for short, carefully quoted commands. It introduces another quoting layer when the shell and AppleScript both use quotation marks. For longer educational examples and reproducible argument passing, a saved script is usually easier to understand and debug.
Can I localize with localized string?
AppleScript includes a localized string command, but useful localization depends on the availability and packaging of the appropriate resources. It does not translate arbitrary text by itself. Test the lookup, supported locales and fallback behavior in the actual app or script bundle.
Is on run the same as on open?
No. A run handler is invoked when a script runs; an open handler responds to files or items sent to an applet through an open event, such as a Finder drop. The event and parameter types differ. Document which one your automation actually uses instead of treating them as interchangeable ways to receive shell arguments.
How can I keep Unicode text intact?
Use harmless test values with accents and non-Latin scripts, then compare the characters received and returned. If a downstream file writer or another application is involved, test that boundary too. A correct input argument does not prove every subsequent component preserves its text.
Why is shell quoting important?
The shell can split, expand or interpret tokens before osascript receives them. A label containing spaces should usually be quoted as one shell argument, and executable code examples should avoid typographic substitution. An argv inspector makes the difference easy to observe without risking data.
What is the safest way to demonstrate do shell script?
For beginners, avoid using it in the initial argument tutorial. If an advanced automation must invoke a shell from AppleScript, treat every supplied value as untrusted, validate the expected form and apply appropriate shell quoting. Do not concatenate arbitrary user text into commands and assume translation makes them safe.
How should errors appear in Terminal?
Capture successful return text separately from errors and verify the actual osascript behavior. The -s flags can affect result and error display. If other programs parse output, use an explicitly designed data format rather than relying on human-readable representations that may be ambiguous.
Can a script work without application permissions?
A read-only on run argv inspector may require no special application control, while a script targeting another macOS app can encounter automation permission checks. Test those actions separately and explain the requirement accurately. Do not mislabel authorization failures as translated input errors.
What should a beginner test before sharing a script?
Run the script with no arguments, one word, a quoted two-word value, a Unicode label and a deliberate malformed input. Check exact received arguments, visible output, errors and the absence of unintended actions. Then have someone else copy the published commands and reproduce the tests.
How do I write a helpful translated error?
Name the missing or invalid input, say what form it needs and show one corrected invocation. Preserve the literal script and option names. If the failure comes from a macOS application or permission subsystem, explain that boundary instead of inventing an AppleScript parsing error.
Is a translated help page enough to release an automation?
No. The script must still handle empty inputs, quoting, permissions, output streams and application side effects correctly. A language reviewer can verify clarity, while a technical reviewer verifies the command works. Both are necessary for trustworthy world-facing instructions.
Primary references and next reading
Read Apple’s AppleScript run-handler guide, AppleScript Commands Reference and the osascript manual page for documented argument and output behavior. For a separate non-Apple CLI parser comparison, see Groovy CliBuilder localization. Always check the on-device manual and supported macOS release when deploying scripts.
Final perspective
An AppleScript automation becomes trustworthy when its users understand what it will receive and what it will do. Multilingual guidance should make that contract clearer, not change hidden assumptions about quoting, handler invocation or application permissions. Begin with a harmless inspector, build accurate local-language messages and test each boundary before introducing any action that could affect a person’s work.