رابط برنامه‌نویسی ترگمان نسخه اختصاصی ماراتن برنامه نویسی موبایل شریف

مقدمه

مترجم دوزبانه‌ی ترگمان به عنوان اولین سامانه‌ی مترجم ماشینی آماری ایرانی در سال ۱۳۹۰ و در قالب یک طرح تحقیقاتی با حمایت پژوهشگاه ارتباطات و فناوری اطلاعات و به مجری‌گری آزمایشگاه فناوری زبان انسانی و یادگیری ماشین دانشگاه امیرکبیر ایجاد و راه‌اندازی شد. این سامانه توانایی ارائه‌ی خدمات ترجمه‌ی متن به متنِ «انگلیسی به فارسی» و «فارسی به انگلیسی» را داشته و به صورت تخصصی بر روی پیکره‌ای مشتمل بر ۳۸ میلیون کلمه از حوزه اخبار و ادبیات داستانی آموزش داده شده است. اصلی‌ترین ویژگی این مترجم، کیفیت بالای آن نسبت به سایر مترجم‌های خودکار فعال در حوزه زبان فارسی می‌باشد. این سامانه به صورت مداوم در حال به‌روزرسانی بوده و در آینده‌ی نزدیک امکانات مختلفی مانند ترجمه گفتار و نمایش تصاویر مرتبط به آن اضافه خواهد شد. همچنین کیفیت ترجمه و حوزه‌های تحت پوشش آن نیز در حال توسعه بوده و به‌مرور از پوشش بهتری نسبت به زبان‌های فارسی و انگلیسی برخوردار خواهد شد.

برای ایجاد امکان بهره‌برداری از این سامانه توسط عموم علاوه بر راه اندازی تارنمای عمومی به نشانی http://targoman.com وب سرویس‌ی نیزتهیه شده است که امکان سرویس‌دهی توسط سایر ستارنما‌ها و نرم افزار‌ها را فراهم می‌آورد. این وب سرویس در حال حاضر به عنوان موتور اصلی ترجمه ماشـینی سامانه‌های موتور جستجوی پارسی‌جو و یوز در حال بـهره‌برداری می باشـد. وب سرویس ترگمان دارای دو نسخه ساده و پیشرفته بوده و در این راهنما تنها مدل ساده وب سرویس نسخه ۷.۰ این سامانه شرح داده می‌شود.

دریافت شناسه

برای استفاده از امکانات وب سرویس ترگمان، نیاز به دریافت API_TOKEN وجود دارد. این توکن از طریق ستاد برگزاری مسابقات یا ایمیل به sales@targoman.com در اختیار شما قرار خواهد گرفت. امکانات و محدودیت‌های زیر به ازای هر توکن وجود خواهد داشت:

نوع لیسانس	امکان ترجمه	امکان ترجمه‌ی پیشرفته	استفاده از دیکشنری	استفاده از دیکشنری پیشرفته	ترجمه اسناد	تلفظ عبارات	محدودیت تعداد کلمه در روز	محدودیت کلی تعداد کلمات
آزمایشی							۱٫۰۰۰	۱۰٫۰۰۰
محدود							۱۰٫۰۰۰
تجاری

توابع

در حال حاضر تنها دو تابع برای API ساده تعریف شده که با هر دو متد GET و POST امکان فراخوانی دارند. برای آشنایی و استفاده از سایر توابع می‌توانید به آدرس http://api.targoman.com مراجعه نمایید.

۱- تابع test

این تابع تنها برای آزمایش صحت ارتباط با API نوشته شده و خروجی آن مشخصات و مجوز‌های Token شما را نمایش می‌دهد. برای استفاده از این تابع کافیست از آدرس ذیل استفاده نمایید. دقت شود که عبارت YOUR_API_TOKEN با توکن ارایه شده جایگزین گردد.:

http://api.targoman.com/v7.0/rest/test/?token=YOUR_API_TOKEN

اگر توکن ارایه شده صحیح باشد خروجی مشابه با ذیل تولید خواهد شد:

{
    "token": "YOUR_API_TOKEN", 
    "tokenID": "YOUR_TOKEN_ID", 
    "userID": "YOUR_TARGOMAN_USER_ID", 
    "ip": "YOU_HAVE_ACCESSED_FROM_IP", 
    "accessCount": "HOW_MANY_TIMES_YOU_HAVE_CALLED_API", 
    "todayReq": "COUNT_OF_TRANSLATION_REQUESTS_YOU_HAVE_SENT_TODAY", 
    "totalReq": "COUNT_OF_TRANSLATION_REQUESTS_YOU_HAVE_SENT_EVER", 
    "privs": {
        "canTranslate": true, 
        "canDic": true, 
        "canDicFull": true, 
        "canDetailed": true
    }
}
                    

اگر توکن وارد شده اشتباه باشد یا خطای دیگری وجود داشته باشد پیغامی مشابه زیر ارایه خواهد شد:

{
    "error": {
        "code": 400, 
        "message": "User blocked or Token Expired"
    }
}

۲- تابع translate

این تابع جهت ترجمه متن مورد استفاده قرار می‌گیرد. برای ترجمه‌ی می توانید از آدرس زیر:

http://api.targoman.com/v7.0/rest/translate/?token=YOUR_API_TOKEN      

پارامتر‌هایی که می‌توانند به این تابع ارایه شوند عبارتند از:

توضیحات	اجباری	پارامتر
متن مورد نظر برای ترجمه.		text
جهت ترجمه که می‌تواندی en_fa برای ترجمه از انگلیسی به فارسی و یا fa_en برای ترجمه فارسی به انگلیسی باشد.		dir
آدرس آی‌پی کاربر نهایی در حال استفاده از سرویس (به توضیحات مراجعه شود)		remoteIP
در صورت ارسال مقدار true ترجمه‌ی پیشرفته همراه با جزییات ترازبندی و پیشنهادات ترجمه درخواست می شود		detailed
در صورت ارسال مقدار true، و وجود نتیجه در مخزن لغت‌نامه برای متن ارسالی، در پاسخ نتیجه‌ی لغت‌نامه باز می‌گردد		dic
در صورت ارسال مقدار true، و وجود نتیجه در مخزن لغت‌نامه برای متن ارسالی، در پاسخ نتیجه‌ی لغت‌نامه به همراه توضیحات اضافی باز می‌گردد (به توضیحات مراجعه شود)		dicfull
کد ترجمه قبلی برای افزایش سرعت در ترجمه‌های پیوسته (به توضیحات مراجعه شود)		tuid

چند مثال:

• درخواست ترجمه متن ساده

  http://api.targoman.com/v7.0/rest/translate/?token=YOUR_API_TOKEN&dir=fa_en&text=است%20آزمایش%20یک%20این&remoteIP=YOUR_CLIENT_IP

  پاسخ نمونه

  {
      "tr": {
          "simple": "This is a test  \\n", 
          "time": 0.047778844833374, 
          "tuid": "eJwzsE5LjE/Nsza0NNIzNLPQMzIAImsj77TIYsvMQgB7RAgm"
      }
  }
  

• درخواست ترجمه با لغت‌نامه

  http://api.targoman.com/v7.0/rest/translate/?token=YOUR_API_TOKEN&dir=en_fa&text=test&remoteIP=YOUR_CLIENT_IP&dic=true

  پاسخ نمونه

  {
      "dic": {
          "Matched": "test", 
          "Translation": "ازمون, ازمودن, ازمون, ازمایش, امتحان کردن, محک, معیار, امتحان کردن, محک زدن, ازمودن کردن"
      }
  }
  

• درخواست ترجمه با جزییات

  http://api.targoman.com/v7.0/rest/translate/?token=YOUR_API_TOKEN&dir=en_fa&text=this%20is%20just%20a%20test%0Aand%20this%20is%20another%20test&remoteIP=YOUR_CLIENT_IP&dic=true&detailed=true

  پاسخ نمونه

  {
      "tr": {
          "base": [
              [
                  " this is just a test", 
                  "این فقط یک آزمایش است  "
              ],
              [
                  "and this is another test", 
                  "و این آزمایش دیگری است  "
              ]
          ],
          "phrases": [
              [
                  [
                      "این ", 
                      0
                  ],
                  [
                      "فقط یک ", 
                      1
                  ],
                  [
                      "آزمایش ", 
                      2
                  ],
                  [
                      "است ", 
                      3
                  ]
              ],
              [
                  [
                      "و این ", 
                      0
                  ],
                  [
                      "آزمایش دیگری ", 
                      1
                  ],
                  [
                      "است ", 
                      2
                  ]
              ]
          ],
          "alignments": [
              [
                  [
                      "this ", 
                      0, 
                      [
                          [
                              "این", 
                              true
                          ],
                          [
                              "به این", 
                              false
                          ],
                          [
                              "در این", 
                              false
                          ],
                          [
                              "که این", 
                              false
                          ],
                          [
                              "از این", 
                              false
                          ]
                      ],
                      [
                          [
                              0, 
                              4
                          ]
                      ]
                  ],
                  [
                      "just a ", 
                      1, 
                      [
                          [
                              "فقط یک", 
                              true
                          ],
                          [
                              "تنها یک", 
                              false
                          ],
                          [
                              "فقط", 
                              false
                          ],
                          [
                              "یک", 
                              false
                          ],
                          [
                              ", فقط یک", 
                              false
                          ]
                      ],
                      [
                          [
                              8, 
                              14
                          ]
                      ]
                  ],
                  [
                      "test ", 
                      2, 
                      [
                          [
                              "آزمایش", 
                              true
                          ],
                          [
                              "تست", 
                              false
                          ],
                          [
                              "آزمون", 
                              false
                          ],
                          [
                              "آزمایشی", 
                              false
                          ],
                          [
                              "امتحان", 
                              false
                          ]
                      ],
                      [
                          [
                              15, 
                              18
                          ]
                      ]
                  ],
                  [
                      "is ", 
                      3, 
                      [
                          [
                              "است", 
                              true
                          ],
                          [
                              "است که", 
                              false
                          ],
                          [
                              "است,", 
                              false
                          ],
                          [
                              "می‌شود", 
                              false
                          ],
                          [
                              "دارد", 
                              false
                          ]
                      ],
                      [
                          [
                              5, 
                              7
                          ]
                      ]
                  ]
              ],
              [
                  [
                      "and this ", 
                      0, 
                      [
                          [
                              "و این", 
                              true
                          ],
                          [
                              "و", 
                              false
                          ],
                          [
                              "است و این", 
                              false
                          ],
                          [
                              "این", 
                              false
                          ],
                          [
                              "و از این", 
                              false
                          ]
                      ],
                      [
                          [
                              0, 
                              8
                          ]
                      ]
                  ],
                  [
                      "another test ", 
                      1, 
                      [
                          [
                              "آزمایش دیگری", 
                              true
                          ],
                          [
                              "آزمایش دیگری را", 
                              false
                          ],
                          [
                              "آزمایشی دیگر", 
                              false
                          ],
                          [
                              "یک آزمایش دیگر", 
                              false
                          ],
                          [
                              "آزمایشی دیگر را", 
                              false
                          ]
                      ],
                      [
                          [
                              12, 
                              23
                          ]
                      ]
                  ],
                  [
                      "is ", 
                      2, 
                      [
                          [
                              "است", 
                              true
                          ],
                          [
                              "است که", 
                              false
                          ],
                          [
                              "است,", 
                              false
                          ],
                          [
                              "می‌شود", 
                              false
                          ],
                          [
                              "دارد", 
                              false
                          ]
                      ],
                      [
                          [
                              9, 
                              11
                          ]
                      ]
                  ]
              ]
          ],
          "time": 0.12706780433655, 
          "tuid": "eJwzsE7Ni09LtDa0NNIzNLPQMzIAIusU94yC5HJbWwB9SQg7"
      }
  }
  

توضیحات اضافی

• آدرس IP کاربر جهت آنالیز آماری استفاده‌کنندگان از سرویس ترگمان مورد استفاده قرار می‌گیرد. در صورتی که این IP به غلط اعلام شود امکان مسدود‌شدن دسترسی API وجود دارد.

---

• در ترگمان این امکان وجود دارد تا ترجمه‌های پیوسته با سرعت بالا پاسخگویی شوند. در صورتی که همزمان با تایپ کاربر می‌خواهید درخواست ترجمه ارسال کنید بهتر است تا روال زیر را پیروی نمایید.
  • ارسال اولین درخواست بدون ارایه TUID یا با TUID برابر با صفر. پس از ترجمه کد TUID توسط سامانه ایجاد و همراه ترجمه ارایه خواهد شد.
  • ارسال درخواست‌های بعدی کاربر که لزوماً در ادامه درخواست قبلی باشند به همراه TUID ارایه شده همراه با آخرین درخواست.
  در صورت عدم رعایت شرایط فوق درخواست‌های ارایه شده به سرورهای مختلف ارایه شده و در نتیجه زمان بیشتری برای ترجمه لازم خواهند داشت. در کد TUID اطلاعاتی برای صحت سنجی پیوسته بودن ترجمه ذخیره شده است در نتیجه در هنگام استفاده از این روال می بایست دقت شود که تنها در صورتی TUID معتبر شناخته شده و به عنوان ترجمه پیوسته در نظر گرفته می شود که تمامی شرایط ذیل وجود داشته باشند:
  • TUID معتبر باشد.
  • IP درخواست کننده تغییر نکرده باشد.
  • جهت ترجمه تغییر نکرده باشد.
  • اولین کلمه درخواست تغییر نکرده باشد.

---

• شرح مفصل نحوه تفسیر خروجی برای حالت پیشرفته ترجمه در مستندات API پیشرفته در آدرس http://api.targoman.com قابل مطالعه است. در ذیل کلیات آن نمایش داده شده است.

  {
      "tr": {
          "base": [
              [
                  "paragraph_1_translated", 
                  "paragraph_1_spell_corected"
              ],
              …, 
              [
                  "paragraph_n_translated", 
                  "paragraph_n_spell_corected"
              ]
          ],
          "phrases": [
              [
                  [
                      "phrase_1", 
                      "index_1"
                  ],
                  …, 
                  [
                      "phrase_n", 
                      "index_n"
                  ]
              ],
              [
                  [
                      "phrase_1", 
                      "index_1"
                  ],
                  [
                      "phrase_2", 
                      "index_2"
                  ]
              ]
          ],
          "alignments": [
              [
                  [
                      "orig_phrase_1", 
                      "index_1", 
                      [
                          [
                              "alternative_1", 
                              true
                          ],
                          …, 
                          [
                              "alternative_n", 
                              false
                          ]
                      ],
                      [
                          [
                              "startpos_1_1", 
                              "endpos_1_1"
                          ],
                          …, 
                          [
                              "startpos_n", 
                              "endpos_1_m"
                          ]
                      ],
                      [
                          "startwpos_1", 
                          "endwpos_1"
                      ]
                  ],
                  …, 
                  [
                      "orig_phrase_n", 
                      "index_n", 
                      [
                          [
                              "alternative_n", 
                              true
                          ],
                          …, 
                          [
                              "alternative_n", 
                              false
                          ]
                      ],
                      [
                          [
                              "startpos_n_1", 
                              "endpos_n_1"
                          ],
                          …, 
                          [
                              "startpos_n_m", 
                              "endpos_n_m"
                          ]
                      ],
                      [
                          "startwpos_n", 
                          "endwpos_n"
                      ]
                  ]
              ],
              [
                  [
                      "orig_phrase_1", 
                      "index_1", 
                      [
                          [
                              "alternative_1", 
                              true
                          ],
                          …, 
                          [
                              "alternative_n", 
                              false
                          ]
                      ],
                      [
                          [
                              "startpos_1_1", 
                              "endpos_1_1"
                          ],
                          …, 
                          [
                              "startpos_n", 
                              "endpos_1_m"
                          ]
                      ],
                      [
                          "startwpos_1", 
                          "endwpos_1"
                      ]
                  ],
                  …, 
                  [
                      "orig_phrase_n", 
                      "index_n", 
                      [
                          [
                              "alternative_n", 
                              true
                          ],
                          …, 
                          [
                              "alternative_n", 
                              false
                          ]
                      ],
                      [
                          [
                              "startpos_n_1", 
                              "endpos_n_1"
                          ],
                          …, 
                          [
                              "startpos_n_m", 
                              "endpos_n_m"
                          ]
                      ],
                      [
                          "startwpos_n", 
                          "endwpos_n"
                      ]
                  ]
              ]
          ],
          "i": "TRANSLATION_TIME", 
          "u": "TRANSLATION_UUID"
      }
  }
  

  
  
  در صورت وجود هرگونه سوال یا مشکل می‌توانید با آدرس support@targoman.com مکاتبه فرمایید.