A lecture is not a collection of knowledge

Minseok Song — Sat, 11 Jul 2026 02:10:50 +0000

Before I think about how to give a lecture, I need to define what a lecture means to me.

A lecture isn't a collection of knowledge that the audience has to memorize. The people in front of me don't need to remember everything I say. Delivering more information doesn't necessarily mean that I've taught them something useful.

For me, a lecture is a chance to share something I've actually tried. I want to talk about where I struggled, what didn't work, and how I dealt with it. The audience doesn't need to repeat my experience exactly. I want them to recognize part of their own problem in it.

This changes how I prepare.

Before building the lecture, I need to understand what the participants are struggling with right now. If I don't know their problem, even correct and useful knowledge can miss them completely.

Preparing a lecture feels like aiming at a target. It doesn't matter how much knowledge I put into the lecture if I'm aiming at the wrong place. I need to aim at a problem the audience actually has.

I want participants to leave thinking, "I can apply that approach to the problem I'm working on." If they feel that way, the lecture has done more than deliver information. It has given them a possible way forward.

I don't think I do this perfectly yet. But this is the kind of lecture I want to give.

Progress Bar Is Not an API

Minseok Song — Fri, 10 Jul 2026 00:41:09 +0000

When a CLI becomes useful, it usually stops being something a person runs only by hand.

Someone puts it in a script. Then someone wraps it in a product workflow. Then another system starts asking a simple question: "What is happening right now?"

That is where a progress bar can become a problem.

For a person, this output is enough:

Translating markdown files  12/40  30%  docs/intro.md

I can see that the command is alive. I can see how far it has moved. I can see the file it is working on.

But another program cannot safely build product state from that sentence. The moment it tries, the progress bar stops being just a UI. It becomes an accidental API.

That boundary was the real lesson behind one part of Co-op Translator v0.20.0. The release added a Rich-based progress UI for people, but it also added structured translation events for systems.

The practical problem was not how to print progress. It was how to keep human output and system state from collapsing into one unstable surface.

This post walks through the design in three steps:

First, why console output is so tempting to parse.

Second, why a better human UI can still break automation.

Third, how a shared event contract can serve the CLI, Python API, MCP, and product integrations such as Localizeflow.

Start with the simple version

Console output is the easiest progress interface to build.

When I run a translation command, I want to answer a few practical questions quickly:

Is the command still running?
Which stage is active?
Which file is being processed?
How much work is left?
Did anything fail?

A progress bar is good at this job. It compresses the current state of the run into something a person can scan.

That is the right first step. A CLI that gives no feedback during a long translation job feels broken, even when it is working.

The problem starts when the same text becomes the only place where state exists.

Imagine Localizeflow running Co-op Translator inside a larger workflow. It needs more than a readable line in the terminal. It needs durable facts:

Which translation job started
Which target language is active
Which stage is running
Which file completed
Which file failed
How many items are done
Whether the run succeeded

If those facts only exist inside display text, Localizeflow has to parse human language to recover machine state.

That is not a stable contract. It is a guess, and guesses become expensive once another product depends on them.

A better UI can still break automation

The awkward part is that the CLI can improve and still break the thing built around it.

Suppose an integration looks for this text:

Translating markdown files: 12/40

Later, the CLI gets nicer. The same information moves into a Rich table, a progress bar, a status panel, or a shorter label.

For the person watching the command, that may be a clear improvement.

For a parser, it may be a failure.

Even a small wording change can be enough:

Retranslating outdated markdowns

Then the label becomes clearer:

Retranslating outdated markdown files

That change should be harmless. It is display text. It should be allowed to get better.

But if another system depends on the exact phrase, a UI edit becomes an integration breaking change.

Once you see that, the fix is not to make the progress bar easier to parse. The fix is to stop asking the progress bar to do two jobs.

Build state once, expose it twice

In v0.20.0, progress information is created once and then exposed through two different surfaces.

The first surface is the human renderer.

In the CLI, Rich can turn translation state into headers, tables, progress bars, and status lines. That output should be pleasant to read. It should also be free to change when a clearer display helps the person using the tool.

The second surface is the system event stream.

External integrations should not scrape console output. They should consume events with a stable schema.

The same progress can be represented as data:

{
  "schema": "co-op.translation.event.v1",
  "type": "stage_progress",
  "stage_key": "translating_markdown_files",
  "stage_label": "Translating markdown files",
  "language": "ko",
  "current_path": "docs/intro.md",
  "completed": 12,
  "total": 40,
  "progress": 30
}

The progress bar and the event can come from the same internal state. They are just shaped for different readers.

The UI gets friendly labels and layout. The event gets stable fields that another system can store, compare, and replay.

Labels explain; keys promise

One small design choice matters a lot here: stage_label and stage_key are separate.

stage_label is for people:

{
  "stage_label": "Translating markdown files"
}

That phrase can change if the CLI becomes clearer.

stage_key is for integrations:

{
  "stage_key": "translating_markdown_files"
}

That value is the one another system should depend on.

This separation protects both sides. The CLI can keep improving its language, and integrations do not have to treat every wording change as a risk.

Progress is a workflow, not only a percentage

A useful event stream should not only report a number.

Progress is a workflow moving through states.

For Co-op Translator, that workflow can be expressed with events such as:

run_started
estimate_ready
stage_started
stage_progress
file_completed
run_completed

Warnings and failures can use their own event types:

warning
file_failed
run_failed

This makes the integration code simpler.

A dashboard can create a job when it receives run_started. It can show token estimates after estimate_ready. It can update visible progress after stage_progress. It can mark the job complete after run_completed.

The dashboard does not need to understand Co-op Translator's terminal sentences.

It needs to understand the event contract.

One contract can serve several interfaces

Co-op Translator is not only a CLI.

It also has a Python API and an MCP server. That means the progress contract should not belong to one terminal renderer.

In the CLI, a person can watch the Rich progress UI. If another system needs machine-readable output, the CLI can write NDJSON events:

translate -l "ko ja" -md --json-events progress.ndjson

In the Python API, callers can receive the same kind of events through a callback:

from co_op_translator.api import run_translation


def on_event(event):
    record_translation_event(job_id, event.to_dict())


run_translation(
    language_codes="ko ja",
    root_dir=".",
    markdown=True,
    progress_callback=on_event,
)

In MCP, run_translation can return events in the tool result payload. Agents and host applications can then understand what happened without scraping terminal output.

The interfaces differ, but the contract is shared:

CLI: Rich renderer and NDJSON event file
Python API: progress_callback
MCP: event payload in the tool result

That is the practical value of the split. The display can evolve without destabilizing API and MCP integrations.

What changes for Localizeflow

From the perspective of Localizeflow, the difference is concrete.

In the fragile version, Localizeflow receives a sentence and tries to extract meaning from it:

Done: Translated README.md to Korean.

From that sentence, it has to infer the file name, language, and completion state.

With structured events, it can store the fact directly:

{
  "type": "file_completed",
  "language": "ko",
  "current_path": "README.md"
}

That event is easy to append to a database. Current job status can be materialized from the event stream. Logs can still exist, but they become supporting context rather than the source of truth for product state.

That is a healthier boundary. A person can read logs while investigating a run. The product can rely on events while managing the workflow.

Rich still matters

Separating events from the UI does not make the UI less important.

It makes the UI easier to improve.

A human-facing CLI should be clear. It should show the command, target language, estimate, current stage, current file, and failures in a form that is easy to scan.

Rich is useful for that:

Headers can group run information
Tables can organize estimates and stage progress
Progress bars can make long jobs easier to follow
GitHub Actions logs can remain reasonably readable

But Rich output should be allowed to change when a better display helps the user.

In this design, Rich renders the human-facing view. The versioned event schema carries the machine-readable state.

The two surfaces come from the same run, but they are accountable to different readers.

The principle

The lesson is simple:

Logs are for humans. Events are for systems.

People can read sentences and infer context. A small wording change is usually fine.

Systems need stable keys, schema versions, event types, and typed fields.

So when designing progress output, the first question should not be:

How do I make this text easier to parse?

The better question is:

Who is going to depend on this output?

If a person will read it, make the UI clear.

If another system will depend on it, provide versioned structured events.

A progress bar still matters. It makes a long-running CLI feel alive.

It just should not be the API.

DEV Community: Minseok Song