\name{translate_line}
\alias{translate_line}
\alias{translation_context}
\title{Line-by-Line Translation of a Sumerian Text}
\description{
\code{translation_context} bundles the settings for a translation project: the project directory (with a \file{lines/} subfolder for saving line files), the dictionaries, the source text, and parameters for the interactive translator.

\code{translate_line} opens the interactive translation tool (\code{\link{translate}}) for a single line. If a saved translation exists for this line, it is loaded so that previous work can be continued. When the user clicks \dQuote{Done}, the result is saved back to the line file.
}
\usage{
translation_context(project_dir, dic = NULL, text = NULL,
                    mapping = NULL, min_freq = c(6, 4, 2),
                    sentence_prob = 1.0)

translate_line(n, context)
}
\arguments{
  \item{project_dir}{Character string. Path to the project directory. Translated lines are saved in the subdirectory \file{lines/} as \file{Line_1.txt}, \file{Line_2.txt}, etc. If \code{text} or \code{dic} are given as filenames without a path, they are assumed to reside in \code{project_dir}.}
  \item{dic}{Dictionaries to use for translation lookup. A character vector of file paths (or filenames relative to \code{project_dir}), a single data frame, or a list of data frames. The first dictionary serves as the primary source. Additional dictionaries serve as fallback references. If \code{NULL}, the built-in dictionary is used.}
  \item{text}{The full text being translated. A file path (or filename relative to \code{project_dir}) or a character vector (one line per element). Needed for n-gram analysis and context display in \code{\link{translate}}.}
  \item{mapping}{A data frame with the sign mapping table, or a file path to a semicolon-separated mapping file. If \code{NULL} (the default), the package's internal mapping is used.}
  \item{min_freq}{Minimum frequency thresholds passed to \code{\link{translate}}. Default is \code{c(6, 4, 2)}.}
  \item{sentence_prob}{Probability that a randomly chosen sign is part of a sentence with a verb, passed to \code{\link{translate}}. Default is \code{1.0}.}
  \item{n}{An integer line number. If a file \file{Line_<n>.txt} exists in the \file{lines/} subdirectory of \code{project_dir}, the saved translation is loaded for revision. Otherwise, the most frequent translation for each substring is looked up in the dictionaries.}
  \item{context}{A context object as created by \code{translation_context}.}
}
\details{
\code{translate_line} performs the following steps:

\enumerate{
  \item If \file{Line_<n>.txt} exists in the \file{lines/} subdirectory, the cuneiform text and previous translations are loaded via \code{\link{fill_substr_info}}.
  \item A project dictionary is built from saved line files using \code{\link{make_dictionary}}. Line \code{n} itself is excluded to avoid confirmation bias.
  \item The interactive translator (\code{\link{translate}}) is opened with the primary dictionary, the project dictionary, and any additional dictionaries as fallback references.
  \item If the user clicks \dQuote{Done}, the result is saved to \file{Line_<n>.txt}. If the window is closed in another way, the result is not saved.
}
}
\value{
\code{translation_context} returns a list of class \code{"translation_context"}.

\code{translate_line} is called for its side effect (opening the interactive translator and saving the result). Returns \code{NULL} invisibly.
}
\seealso{
\code{\link{translate}} for the underlying interactive translation tool,
\code{\link{fill_substr_info}} for reading back a saved translation,
\code{\link{make_dictionary}} for creating a dictionary from translated lines
}
\examples{
# Note: The folder containing the built-in project
#       is copied to a temporary directory.
#       This prevents you from altering the package files.

path  <- system.file("extdata", package = "sumer")

file.copy(
  from = file.path(path, "project"),
  to   = tempdir(),
  recursive = TRUE
)

ctx <- translation_context(
  project_dir = file.path(tempdir(), "project"),
  text        = "enki_and_the_world_order.txt",
  dic         = file.path(path, "sumer-dictionary.txt"),
  sentence_prob = 0.25
)
ctx

\dontrun{
# Translate line 29 (opens interactive translator)
translate_line(29, ctx)

# Confirm that your changes are still there:
translate_line(29, ctx)

# Continue with the next line:
translate_line(30, ctx)
}
}
\keyword{utilities}
