Installation

Prerequisites

• macOS with Excel for Mac (the add-in requires the CustomFunctionsRuntime 1.1 requirement set)
• LM Studio with its local server started and a model loaded
• Either Docker (the default path used by the npm run docker:* scripts) or Python 3.12+ to run the server directly
• openssl and security, both of which ship with macOS

No certificate is shipped

The repository deliberately contains no TLS key or certificate. certs/ is git-ignored apart from a .gitkeep placeholder. You must generate your own key pair before the host will start — scripts/dev_server.py exits with a non-zero status and prints the expected paths if certs/localhost.pem or certs/localhost-key.pem is missing.

1. Generate your own localhost certificate

Office Add-ins must be served over HTTPS, and a self-signed certificate is acceptable for local development as long as the machine trusts it. Run this from the repository root:

mkdir -p certs
openssl req -x509 -newkey rsa:2048 \
  -keyout certs/localhost-key.pem \
  -out certs/localhost.pem \
  -days 365 -nodes \
  -subj "/CN=localhost" \
  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"

This writes an unencrypted private key (-nodes) that is only ever used by the local dev server. Keep it out of version control — the provided .gitignore already does that. Tighten the permissions if you like:

chmod 600 certs/localhost-key.pem

2. Trust the certificate

Excel will refuse to load the add-in if the certificate is not trusted. The repository ships a helper, scripts/trust-localhost-cert.sh, exposed as an npm script:

npm run mac:trust-cert

The script checks that certs/localhost.pem exists, then runs:

security add-trusted-cert -d -r trustRoot \
  -k "$HOME/Library/Keychains/login.keychain-db" \
  certs/localhost.pem

macOS will prompt for your password. To undo it later:

security delete-certificate -c localhost \
  "$HOME/Library/Keychains/login.keychain-db"

Understand what you are trusting

-r trustRoot marks this self-signed certificate as a trusted root in your login keychain. Anything holding that private key can then impersonate localhost for your user account. Generate the key yourself, never share it, never reuse one across machines, and remove the trust entry when you are finished with the add-in.

3. Start the add-in host

Docker (default)

npm run docker:up

This runs docker compose up --build -d. The image contains only scripts/ and web/; certs/ is mounted read-only at runtime rather than copied in, so a TLS private key never ends up inside an image layer. The certificate must exist on the host before you start the container. It binds 0.0.0.0:3000 inside the container, published to the host as 127.0.0.1:3000 only — the proxy is unauthenticated, so it is deliberately not reachable from your LAN. It reaches LM Studio through http://host.docker.internal:1234/v1.

Python directly

npm start
# equivalent to: python3 scripts/dev_server.py

Run directly, the server binds 127.0.0.1:3000 and talks to LM Studio at http://127.0.0.1:1234/v1. No third-party Python packages are required.

Check that it is up:

curl -k https://localhost:3000/api/health

A healthy response reports the LM Studio base URL and the active model. See Configuration for every environment variable.

4. Start LM Studio’s local server

In LM Studio, open the Developer tab, start the local server, and confirm a model is loaded. The proxy calls GET /v1/models and uses the first entry it finds unless you pin LM_STUDIO_MODEL.

5. Sideload the manifest into Excel

npm run install-manifest

scripts/install_manifest.sh copies manifest.xml to:

~/Library/Containers/com.microsoft.Excel/Data/Documents/wef/cell-translator-manifest.xml

6. Register the functions once

1. Quit Excel completely and reopen it.

2. Open a workbook and go to Home → Add-ins.

3. Launch Cell Translator once. This first launch is what registers the custom functions for your Excel user profile.

4. In any cell, try:

   =XLT.TRANSLATE(A1,"de")

If Excel shows #NAME?, the custom-functions runtime has not registered yet — see Troubleshooting.

Documentation site

This site lives in docs/ and is a standard Astro Starlight project:

cd docs
npm install
npm run build