[ELPA] New package proposal: org-translate

[ELPA] New package proposal: org-translate

[Eric Abrahamsen]

Hi all,

I've added version 0 of a package called org-translate to ELPA, and I'm
proposing it for release. It's a translation environment based on Org.
It's not quite a full-on CAT tool, but I suppose has the potential to
get there. I'm posting the Commentary section from the library below.
Comments/suggestions/complaints very welcome!

Eric


;;; Commentary:

;; This library contains the `org-translate-mode' minor mode to be
;; used on top of Org, providing translation-related functionality.
;; It is not a full-fledged CAT tool.  It essentially does two things:
;; manages segmentation correspondences between the source text and
;; the translation, and manages a glossary which can be used for
;; automatic translation, displaying previous usages, etc.

;; Currently assumes a single file holding a single translation
;; project, with three separate headings for source text, translation,
;; and glossary (other headings will be ignored).  Each translation
;; project has five local settings, each of which also has a global
;; default value.  The first three settings are used to locate the org
;; subtrees representing source text, translation text, and glossary.
;; The fourth setting defines the segmentation strategy: the source
;; text can be segmented by sentence, paragraph, or regular
;; expression.  The fifth setting determines the character to be used
;; to delimit segments.

;; While translating, use "C-M-n" to start a new segment in the
;; translation text.  "C-M-b" and "C-M-f" will move forward and back
;; between segments, maintaining the correspondence with the source
;; text.  If the source text highlighting gets "lost", reset it with
;; "C-M-t".  To add a new glossary item, move to the source window,
;; put the region on the new item, and use M-x ogt-add-glossary-item.
;; In the translation text, add a translation of the next glossary
;; item with "C-M-y".

;; Translation projects can optionally be defined and configured in
;; the option `ogt-translation-projects' (see docstring for details)
;; though this is only useful if you're working on multiple projects
;; with different settings.

;; The functions `ogt-start-translating' and `ogt-stop-translating'
;; can be used to start and stop a translation session.  The first use
;; of the latter command will save the project in your bookmarks file,
;; after which `ogt-start-translating' will offer the project to work
;; on.

;; TODO:

;; - Generalize the code to work in text-mode as well as Org,
;;   using 2C-mode instead of Org subtrees.
;; - Support multi-file translation projects.
;; - Import/export TMX translation databases.
;; - Provide for other glossary backends: eieio-persistent, xml,
;;   sqlite, etc.
;; - Provide integration with `org-clock': set a custom property on a
;;   TODO heading indicating that it represents a translation project.
;;   Clocking in both starts the clock, and sets up the translation
;;   buffers.  Something like that.

Re: [ELPA] New package proposal: org-translate

[Stefan Kangas]

Hi Eric,

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> I've added version 0 of a package called org-translate to ELPA, and I'm
> proposing it for release. It's a translation environment based on Org.
> It's not quite a full-on CAT tool, but I suppose has the potential to
> get there. I'm posting the Commentary section from the library below.
> Comments/suggestions/complaints very welcome!

I am happy to hear a package like this is in the works, as I do and have
done a lot of translating in Emacs.

I realize this is just a first draft, but I'll just add my thoughts
from trying the package.

First, I think the Commentary should clearly explain how to set up your
org file and get started.  It explains it only abstractly, but
preferably should do so in concrete steps.

The minor mode documentation should include an overview of the key
bindings.  I would also appreciate an overview of the keybindings and
expected workflow in the Commentary section.

`ogt-start-translating' while in an org buffer should just start with
the current org buffer.  It works after setting up a bookmark, but I'm
not sure requiring the user to keep a bookmark is the best design
choice.  (Also, there is no completion for the bookmarks.)

So I set up the bookmark, and now it asks to segment the file.  Seems to
work fine, and I get markers in my file (but all the markers say ""
for some reason).  Now my file looks like:

    * Original

     In the early hours of 9 September

The first segment is from after the "l" in "Original" to before "In".
I guess that should rather be ignored.

If I remove the headline and run `ogt-forward-segment', I see the
following backtrace:

  goto-char(nil)
  (progn (select-window (car save-selected-window--state) 'norecord)
(goto-char ogt-probable-source-location) (re-search-forward (string
ogt-segmentation-character) nil t arg) (set-marker
ogt-probable-source-location (point)) (ogt-highlight-source-segment)
(recenter))
  (unwind-protect (progn (select-window (car
save-selected-window--state) 'norecord) (goto-char
ogt-probable-source-location) (re-search-forward (string
ogt-segmentation-character) nil t arg) (set-marker
ogt-probable-source-location (point)) (ogt-highlight-source-segment)
(recenter)) (internal--after-with-selected-window
save-selected-window--state))
  (save-current-buffer (unwind-protect (progn (select-window (car
save-selected-window--state) 'norecord) (goto-char
ogt-probable-source-location) (re-search-forward (string
ogt-segmentation-character) nil t arg) (set-marker
ogt-probable-source-location (point)) (ogt-highlight-source-segment)
(recenter)) (internal--after-with-selected-window
save-selected-window--state)))
  (let ((save-selected-window--state
(internal--before-with-selected-window ogt-source-window)))
(save-current-buffer (unwind-protect (progn (select-window (car
save-selected-window--state) 'norecord) (goto-char
ogt-probable-source-location) (re-search-forward (string
ogt-segmentation-character) nil t arg) (set-marker
ogt-probable-source-location (point)) (ogt-highlight-source-segment)
(recenter)) (internal--after-with-selected-window
save-selected-window--state))))
  (if (marker-position ogt-probable-source-location) (let
((save-selected-window--state (internal--before-with-selected-window
ogt-source-window))) (save-current-buffer (unwind-protect (progn
(select-window (car save-selected-window--state) 'norecord) (goto-char
ogt-probable-source-location) (re-search-forward (string
ogt-segmentation-character) nil t arg) (set-marker
ogt-probable-source-location (point)) (ogt-highlight-source-segment)
(recenter)) (internal--after-with-selected-window
save-selected-window--state)))) (ogt-update-source-location))
  ogt-forward-segment(1)
  funcall-interactively(ogt-forward-segment 1)
  command-execute(ogt-forward-segment)

Saving the file and opening it again, I now see " " in every location
where there previously were markers.  Running `ogt-start-translating'
doesn't give a backtrace, but the message: "org-back-to-heading: Before
first headline at position 121 in buffer trans.org"

So I re-add the "Original" headline and try again, seems to work now and
the characters above are again the markers "".  I'm not sure if I'm
supposed to type the text directly in place?  I would rather have the
translation text in a separate window, fixed in place and highlighted,
and I'd like to see only the segment I'm currently translating with the
rest of the text highlighted.  More like OmegaT or a proper CAT
software.

That's basically as far as I got for now.

Thanks again for working on this.

Best regards,
Stefan Kangas

Re: [ELPA] New package proposal: org-translate

[Eric Abrahamsen]

Stefan Kangas <stefankangas@gmail.com> writes:

> Hi Eric,
>
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>> I've added version 0 of a package called org-translate to ELPA, and I'm
>> proposing it for release. It's a translation environment based on Org.
>> It's not quite a full-on CAT tool, but I suppose has the potential to
>> get there. I'm posting the Commentary section from the library below.
>> Comments/suggestions/complaints very welcome!
>
> I am happy to hear a package like this is in the works, as I do and have
> done a lot of translating in Emacs.
>
> I realize this is just a first draft, but I'll just add my thoughts
> from trying the package.

Thank you very much for testing!

> First, I think the Commentary should clearly explain how to set up your
> org file and get started.  It explains it only abstractly, but
> preferably should do so in concrete steps.
>
> The minor mode documentation should include an overview of the key
> bindings.  I would also appreciate an overview of the keybindings and
> expected workflow in the Commentary section.

Yep, others have also mentioned that the docs are lacking, I'll add this
first.

> `ogt-start-translating' while in an org buffer should just start with
> the current org buffer.  It works after setting up a bookmark, but I'm
> not sure requiring the user to keep a bookmark is the best design
> choice.  (Also, there is no completion for the bookmarks.)

`ogt-start-translating' is really only useful if you're not in the org
buffer already, and if you've chosen to use bookmarks. Maybe I should
rename it `ogt-open-bookmark' or something. Otherwise, just turning on
the minor mode is all you need.

You only get completion if you've already bookmarked a translation
project -- `start-translating' will only offer bookmarks that represent
existing translation projects.

> So I set up the bookmark, and now it asks to segment the file. Seems to
> work fine, and I get markers in my file (but all the markers say ""
> for some reason).  Now my file looks like:
>
>     * Original
>
>      In the early hours of 9 September
>
> The first segment is from after the "l" in "Original" to before "In".
> I guess that should rather be ignored.
>
> If I remove the headline and run `ogt-forward-segment', I see the
> following backtrace:

I think all this is just a symptom of the mode being unable to identify
which subtree is the original text, and which is the translation. I
think in that case it should just error out with a helpful message,
rather than limping along and segmenting incorrectly.

[...]

> Saving the file and opening it again, I now see " " in every location
> where there previously were markers. Running `ogt-start-translating'
> doesn't give a backtrace, but the message: "org-back-to-heading: Before
> first headline at position 121 in buffer trans.org"
>
> So I re-add the "Original" headline and try again, seems to work now and
> the characters above are again the markers "". I'm not sure if I'm
> supposed to type the text directly in place? I would rather have the
> translation text in a separate window, fixed in place and highlighted,
> and I'd like to see only the segment I'm currently translating with the
> rest of the text highlighted. More like OmegaT or a proper CAT
> software.

I'm still thinking this is a result of the mode misidentifying the parts
of the buffer. Your notes above have just " " and "" where you're
talking about the markers -- I'm assuming the actual characters were
stripped out on sending.

If you get the parts properly identified, I think the mode will behave
the way you want it to: source text in one window, translation in
another, and the source window follows along as you progress with the
translation.

> That's basically as far as I got for now.

Thanks for test-running what's obviously a half-baked library! I guess I
hadn't yet gotten out of my own head and thought about how a new user
would approach the code.

Step one should be making sure that the buffer contains one top-level
heading for each of the source text, translation text, and glossary.
Look at the values (and docstrings) of the
`ogt-default-{source,translation,glossary}-locator' options to see how
to tell the minor mode to locate each subtree.

But I'll put all this in the Commentary section later today.

Thanks again,
Eric

Re: [ELPA] New package proposal: org-translate

[Eric Abrahamsen]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> Stefan Kangas <stefankangas@gmail.com> writes:
>
>> Hi Eric,
>>
>> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>>
>>> I've added version 0 of a package called org-translate to ELPA, and I'm
>>> proposing it for release. It's a translation environment based on Org.
>>> It's not quite a full-on CAT tool, but I suppose has the potential to
>>> get there. I'm posting the Commentary section from the library below.
>>> Comments/suggestions/complaints very welcome!
>>
>> I am happy to hear a package like this is in the works, as I do and have
>> done a lot of translating in Emacs.
>>
>> I realize this is just a first draft, but I'll just add my thoughts
>> from trying the package.
>
> Thank you very much for testing!

Okay, I think I've addressed all your concerns, along with some other
improvements. Hope you're still interested in test-running this!

I'm also not very happy about the keybindings, all of which start with
"C-M-". I started with "C-M-f" and "C-M-b" for moving by segments (I
considered setting `ogt-forward-segment' to the local
`forward-sexp-function' and leaving it at that), and I think just went
on from there to eat up more "C-M-" bindings. Org leaves so little left
on the keyboard!

Re: [ELPA] New package proposal: org-translate

[Eric Abrahamsen]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> Stefan Kangas <stefankangas@gmail.com> writes:
>
>> Hi Eric,
>>
>> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>>
>>> I've added version 0 of a package called org-translate to ELPA, and I'm
>>> proposing it for release. It's a translation environment based on Org.
>>> It's not quite a full-on CAT tool, but I suppose has the potential to
>>> get there. I'm posting the Commentary section from the library below.
>>> Comments/suggestions/complaints very welcome!
>>
>> I am happy to hear a package like this is in the works, as I do and have
>> done a lot of translating in Emacs.
>>
>> I realize this is just a first draft, but I'll just add my thoughts
>> from trying the package.
>
> Thank you very much for testing!

Okay, I think I've addressed all your concerns, along with some other
improvements. Hope you're still interested in test-running this!

I'm also not very happy about the keybindings, all of which start with
"C-M-". I started with "C-M-f" and "C-M-b" for moving by segments (I
considered setting `ogt-forward-segment' to the local
`forward-sexp-function' and leaving it at that), and I think just went
on from there to eat up more "C-M-" bindings. Org leaves so little left
on the keyboard!